API-uri explicate: ce sunt, cum funcționează și cum testezi primul request
Află ce este un API, cum funcționează endpoint-urile HTTP, metodele GET și POST, răspunsurile JSON și cum testezi o cerere reală cu curl și JavaScript.
Reprezentare vizuală a comunicării dintre o aplicație și un API web.
Un magazin online care afișează produse, o aplicație meteo care preia prognoza și un program care citește informații dintr-un cont folosesc adesea aceeași idee: un sistem cere date sau solicită o acțiune de la un alt sistem. Legătura dintre ele poate fi realizată printr-un API.
În acest ghid explicăm ce înseamnă API, cum funcționează o cerere HTTP, ce sunt endpoint-urile, metodele și răspunsurile JSON și cum poți testa primul request. Vom folosi un exemplu public din GitHub și apoi îl vom accesa din JavaScript, fără să presupunem că toate API-urile funcționează identic.
Dacă ești la început cu programarea web, articolul se leagă de ghidul nostru despre JavaScript pentru începători. Pentru partea de rețea, poți recapitula și ce se întâmplă când deschizi un site: DNS, HTTPS și încărcarea paginii.
Ce este un API și de ce îl folosesc aplicațiile
API vine de la Application Programming Interface, adică interfață de programare a aplicațiilor. Este un set de reguli și puncte de acces prin care un program poate solicita date sau funcții oferite de un alt program. API-ul stabilește ce cereri sunt acceptate, ce informații trebuie trimise și în ce formă poate veni răspunsul.
Un exemplu simplu: o aplicație de pe telefon nu trebuie să păstreze local toate datele despre vreme. Ea poate cere unui serviciu meteo prognoza pentru o localitate. Serviciul primește solicitarea, verifică parametrii și returnează date structurate pe care aplicația le transformă în temperaturi, pictograme și grafice.
API-ul nu este neapărat o aplicație separată și nici nu înseamnă automat o adresă web. Există API-uri pentru biblioteci software, sisteme de operare, baze de date și dispozitive hardware. În dezvoltarea web, expresia „API” se referă frecvent la un serviciu accesibil prin rețea, dar acesta este doar unul dintre modurile de utilizare.
Cum funcționează un API web: cerere și răspuns
Un API web funcționează adesea prin modelul client-server. Clientul poate fi un browser, o aplicație mobilă, un program de calculator sau un alt server. Acesta trimite o cerere către serviciu, iar serverul răspunde cu un cod de stare, antete și, de regulă, un corp de răspuns.
În multe API-uri moderne, schimbul de date se face prin HTTP sau HTTPS, iar corpul răspunsului este format din JSON. HTTP descrie modul în care sunt transmise cererile și răspunsurile; API-ul adaugă regulile proprii pentru resursele și operațiile pe care le pune la dispoziție. Poți consulta și explicația MDN despre modul de funcționare al HTTP.
Din ce este alcătuită o cerere
- URL sau endpoint: adresa resursei pe care vrei să o accesezi.
- Metoda HTTP: indică operația solicitată, de exemplu citirea sau trimiterea unor date.
- Antete (headers): transmit metadate, precum formatul acceptat sau informații de autentificare.
- Parametri: pot selecta o anumită resursă, filtra rezultatele sau controla pagina de rezultate.
- Corp (body): conține datele trimise de client pentru metodele care folosesc un corp de cerere.
Nu toate cererile folosesc toate aceste elemente. Un request simplu de tip GET poate avea doar o adresă și câteva antete, în timp ce o cerere POST poate include și un corp JSON.
Endpoint, resursă și parametri: cum citești adresa unui API
Endpoint-ul este adresa specifică la care API-ul primește o anumită cerere. Într-un serviciu care gestionează produse, ai putea întâlni rute precum /products pentru o colecție și /products/42 pentru un produs identificat prin numărul 42. Aceste adrese sunt doar exemple ilustrative; fiecare serviciu își definește propriile rute.
Parametrii pot apărea în calea URL-ului sau după semnul întrebării. De exemplu, ?page=2&limit=20 poate cere a doua pagină, cu cel mult 20 de rezultate, dacă API-ul respectiv documentează acești parametri. Nu presupune că numele sau limitele sunt universale: verifică întotdeauna documentația serviciului.
Metodele HTTP folosite cel mai des de API-uri
Metoda HTTP descrie intenția cererii. Cele mai întâlnite în API-urile web sunt:
- GET: solicită citirea unei resurse. În mod normal, nu este folosit pentru a modifica date pe server.
- POST: trimite date către o resursă, de exemplu pentru crearea unei înregistrări sau declanșarea unei acțiuni.
- PUT: înlocuiește reprezentarea unei resurse cu datele transmise, conform regulilor API-ului.
- PATCH: solicită modificarea parțială a unei resurse.
- DELETE: solicită ștergerea unei resurse.
Aceste metode au semnificații definite de HTTP, dar API-ul stabilește ce operații permite pentru fiecare endpoint. Un serviciu poate accepta GET pentru o rută și poate refuza POST sau DELETE pe aceeași adresă. MDN explică diferențele în documentația despre metodele de cerere HTTP.
JSON: formatul în care primești frecvent datele
JSON (JavaScript Object Notation) este un format textual pentru reprezentarea datelor structurate. Este folosit pe scară largă deoarece este relativ ușor de citit și poate fi procesat în numeroase limbaje de programare, nu doar în JavaScript.
{
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"private": false,
"html_url": "https://github.com/octocat/Hello-World"
}
Acesta este un exemplu de obiect JSON cu proprietăți și valori. Șirurile de caractere sunt scrise între ghilimele duble, valorile logice pot fi true sau false, iar obiectele pot conține liste și alte obiecte. Într-un răspuns real, câmpurile disponibile depind de endpoint și de permisiunile cererii.
Testează primul request cu API-ul public GitHub
Pentru un prim test folosim endpoint-ul GitHub care returnează informații despre un repository public. Documentația oficială îl numește „Get a repository”. Pentru resurse publice, acest endpoint poate fi accesat și fără autentificare, în limitele și condițiile serviciului.
Deschide terminalul și execută cererea de mai jos. Comanda folosește GET și cere răspunsul în formatul JSON recomandat de GitHub:
curl --request GET --url "https://api.github.com/repos/octocat/Hello-World" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2026-03-10"
Dacă request-ul este acceptat, terminalul afișează un obiect JSON cu informații despre repository. Poți căuta câmpuri precum full_name, html_url sau private. Nu este necesar să copiezi întregul răspuns: identifică doar câmpurile de care ai nevoie.
Înainte să folosești un endpoint într-un proiect, verifică documentația lui pentru metoda acceptată, parametrii necesari, antete, autentificare și codurile de răspuns. Ghidul oficial GitHub Getting started with the REST API explică structura cererilor, antetele și exemplele de utilizare, iar pagina REST API endpoints for repositories descrie endpoint-urile pentru repository-uri.
Accesează API-ul din JavaScript cu fetch()
Într-o aplicație web, JavaScript poate trimite cereri HTTP cu funcția fetch(). Aceasta returnează un Promise care se rezolvă cu un obiect Response atunci când serverul răspunde. Este important să verifici response.ok: o eroare HTTP precum 404 nu respinge automat Promise-ul, deci trebuie tratată separat.
async function incarcaRepository() {
const url = 'https://api.github.com/repos/octocat/Hello-World';
try {
const response = await fetch(url, {
headers: {
Accept: 'application/vnd.github+json'
}
});
if (!response.ok) {
throw new Error('Răspuns HTTP: ' + response.status);
}
const date = await response.json();
console.log('Repository:', date.full_name);
console.log('Adresă:', date.html_url);
} catch (error) {
console.error('Cererea nu a putut fi finalizată:', error);
}
}
incarcaRepository();
Exemplul este potrivit pentru un endpoint public care permite cereri din browser. Alte servicii pot impune reguli CORS diferite. Dacă browserul blochează citirea răspunsului din cauza CORS, soluția corectă este configurarea permisivă și controlată a serverului sau trimiterea cererii prin propriul backend, nu folosirea opțiunii no-cors pentru a încerca să ocolești restricția. Documentația MDN Using the Fetch API explică verificarea răspunsului, citirea JSON și cererile cross-origin.
Dacă vrei să înțelegi mai bine variabilele, funcțiile și lucrul cu DOM înainte de a integra cereri de rețea, continuă cu proiectul practic JavaScript pentru începători.
Codurile de stare: cum îți dai seama dacă request-ul a reușit
Serverul trimite un cod numeric care indică rezultatul cererii. Câteva valori întâlnite frecvent sunt:
- 200 OK: cererea a fost procesată cu succes.
- 201 Created: cererea a dus la crearea unei resurse.
- 204 No Content: operația a reușit, dar răspunsul nu conține un corp de date.
- 400 Bad Request: cererea are o problemă de sintaxă sau de parametri.
- 401 Unauthorized: cererea nu este autentificată corespunzător.
- 403 Forbidden: serverul refuză accesul, chiar dacă cererea a ajuns la el.
- 404 Not Found: resursa cerută nu a fost găsită sau ruta nu este disponibilă.
- 429 Too Many Requests: au fost trimise prea multe cereri într-un interval de timp.
- 500 Internal Server Error: serverul a întâmpinat o problemă pe care nu a putut-o trata.
Codul singur nu explică întotdeauna cauza exactă. Citește și corpul răspunsului, antetele și documentația API-ului. Lista completă și clasificarea codurilor sunt disponibile în referința MDN despre codurile de stare HTTP.
Autentificare, chei API și protejarea datelor
Unele API-uri permit citirea datelor publice fără autentificare. Altele cer un cont, un token sau o cheie API pentru a identifica aplicația și a stabili ce operații are voie să execute. Autentificarea nu înseamnă că utilizatorul primește automat acces la toate resursele: permisiunile pot fi limitate pe proiect, cont sau tip de operație.
- Nu publica token-uri sau chei API în codul JavaScript livrat browserului, în repository-uri publice sau în capturi de ecran.
- Păstrează secretele pe server, de preferat în variabile de mediu sau într-un manager de secrete potrivit proiectului.
- Acordă doar permisiunile strict necesare și evită token-urile cu acces mai larg decât ai nevoie.
- Folosește HTTPS și nu trimite parole sau token-uri în parametrii URL dacă documentația nu cere explicit acest lucru.
- Dacă o cheie ajunge publică, revoc-o sau rotește-o; ștergerea ei din ultima versiune a codului nu elimină automat urmele din istoricul Git.
Dacă lucrezi cu Git și GitHub, articolul nostru Git și GitHub pentru începători explică de ce fișierele cu secrete nu trebuie incluse în repository și ce trebuie făcut dacă ai publicat accidental o cheie.
Limite de utilizare, paginare și versiuni
Un API public nu garantează acces nelimitat. Furnizorul poate impune un număr maxim de cereri într-un interval, limite pentru anumite operații sau condiții diferite pentru utilizatorii autentificați. Dacă primești 429, citește antetele și documentația pentru a afla când poți relua solicitările. Nu trimite cereri repetate într-o buclă rapidă pentru a forța răspunsul.
Când o colecție are multe rezultate, API-ul poate folosi paginare. În loc să trimită mii de înregistrări într-un singur răspuns, serviciul returnează un număr limitat și oferă parametri sau legături pentru pagina următoare. Unele API-uri folosesc numere de pagină, altele cursor sau antete de navigare.
Versiunile API sunt importante deoarece structura răspunsurilor și comportamentul endpoint-urilor se pot schimba. Verifică versiunea documentată, data de retragere a versiunilor vechi și modul în care furnizorul anunță modificările. Nu presupune că un exemplu găsit într-un tutorial vechi va funcționa neschimbat.
Greșeli frecvente când testezi un API
- Endpoint scris greșit: verifică domeniul, calea, majusculele și parametrii.
- Metodă nepotrivită: compară metoda folosită cu cea cerută în documentație.
- Antet lipsă: unele servicii cer explicit un format Accept, un Content-Type sau o versiune API.
- JSON invalid: verifică ghilimelele, virgulele și tipurile de valori din corpul cererii.
- Autentificare expirată: verifică token-ul, permisiunile și data de expirare, dacă există.
- Confuzie între 401 și 403: una indică de regulă lipsa autentificării valide, cealaltă refuzul accesului.
- CORS confundat cu autentificarea: o restricție CORS este aplicată de browser pentru accesul la răspuns; nu dovedește singură că token-ul este greșit.
- Răspuns tratat automat ca succes: verifică statusul HTTP înainte să folosești datele primite.
Documentație oficială pentru următorul pas
Pentru a aprofunda conceptele, începe cu ghidul MDN despre HTTP, apoi consultă referințele pentru metodele HTTP și codurile de stare. Pentru integrarea într-o pagină web, parcurge ghidul MDN Using the Fetch API.
Dacă vrei să lucrezi cu un API real, documentația GitHub pentru primii pași cu REST API și pentru endpoint-urile repository-urilor oferă exemple concrete de cereri, antete și răspunsuri.
De la primul request la o integrare utilă
Un API devine mai ușor de înțeles când îl privești ca pe un contract între două programe: clientul respectă formatul cererii, iar serviciul răspunde conform regulilor publicate. Începe cu o operație GET pe date publice, observă endpoint-ul și JSON-ul primit, apoi adaugă treptat parametri și tratarea erorilor.
După ce poți explica fiecare parte a request-ului, încearcă o integrare mică în JavaScript și documentează ce se întâmplă când serverul răspunde cu o eroare, când conexiunea cade sau când limita de utilizare este atinsă. Acest exercițiu te ajută să construiești aplicații care nu doar comunică cu un serviciu, ci gestionează corect și situațiile în care lucrurile nu merg conform așteptărilor.
Descoperă mai multe la Scoala IT
Abonează-te ca să primești ultimele articole prin email.