...
← Blog Dezvoltare web

Ce este un REST API, explicat cu exemple în Node.js

Ce este un REST API: sigla Node.js în centru, legată de siglele JavaScript, SQL și Docker

Un REST API este o interfață prin care două programe schimbă date pe internet folosind HTTP, după reguli simple: fiecare lucru are o adresă (de exemplu /produse/2), iar ce vrei să faci cu el spui prin metoda cererii: GET citește, POST creează, PUT sau PATCH modifică, DELETE șterge. Răspunsul vine de obicei în format JSON.

În articol vezi cum arată o cerere și un răspuns reale, un mic REST API în Node.js pe care îl poți rula în 5 minute și greșelile pe care le face aproape oricine la primul API.

Ce este un REST API, pe înțelesul tuturor

Un REST API e ca ghișeul unei instituții care are reguli clare: știi la ce ghișeu mergi, ce formular depui și ce primești înapoi. API vine de la Application Programming Interface și înseamnă orice mod prin care un program îi oferă altuia acces la datele sau funcțiile lui. REST (Representational State Transfer) este un stil de a construi astfel de API-uri peste web, descris pentru prima dată de Roy Fielding în teza lui de doctorat din 2000.

Concret, când deschizi aplicația unei bănci și vezi soldul, aplicația de pe telefon trimite o cerere de tipul GET /conturi/123/sold către serverul băncii. Serverul verifică cine ești, citește soldul din baza de date și îl trimite înapoi ca text structurat. Aplicația doar îl afișează frumos. Același API poate fi folosit de site, de aplicația mobilă și de un partener extern, fiecare cu interfața lui.

Cum arată o cerere și un răspuns într-un REST API

Orice comunicare cu un REST API are două părți: cererea trimisă de client și răspunsul trimis de server. Cererea conține metoda, adresa și, uneori, date; răspunsul conține un cod de stare și datele cerute.

O cerere care creează un produs nou într-un magazin online arată așa:

POST /produse HTTP/1.1
Host: magazin.exemplu.ro
Content-Type: application/json

{"nume": "Miere de salcâm", "pret": 32}

Iar răspunsul serverului:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{"id": 3, "nume": "Miere de salcâm", "pret": 32}

Prima linie a cererii spune ce vrei (POST, adică „creează”) și unde (/produse). Antetele, cum e Content-Type, descriu ce trimiți. Corpul cererii conține datele în JSON, un format text cu perechi „cheie: valoare” pe care îl citește ușor orice limbaj. Răspunsul începe cu codul 201, care înseamnă „am creat resursa”, și îți dă înapoi produsul, acum cu un id primit de la server.

Metodele HTTP și codurile de stare pe care le folosești zilnic

Într-un REST API, aceeași adresă face lucruri diferite în funcție de metoda HTTP. Tabelul de mai jos acoperă aproape tot ce întâlnești într-un proiect obișnuit.

MetodăCe faceExempluRăspuns tipic
GETCitește o resursă sau o listăGET /produse, GET /produse/2200 OK
POSTCreează o resursă nouăPOST /produse cu datele în corp201 Created
PUTÎnlocuiește complet o resursăPUT /produse/2 cu toate câmpurile200 OK
PATCHModifică doar câteva câmpuriPATCH /produse/2 cu {"pret": 12}200 OK
DELETEȘterge o resursăDELETE /produse/2204 No Content

Codurile de stare îți spun din prima cifră ce s-a întâmplat: 2xx înseamnă succes, 4xx înseamnă că cererea are o problemă (400 date greșite, 401 nu ești autentificat, 403 nu ai voie, 404 nu există), iar 5xx înseamnă că s-a stricat ceva pe server. Lista completă e în documentația MDN despre codurile de stare HTTP.

Câteva reguli fac un API să fie „RESTful” și nu doar „un server care răspunde”:

  • Adresele numesc lucruri, nu acțiuni: /produse/2, nu /stergeProdus?id=2.
  • Fiecare cerere e independentă. Serverul nu ține minte ce ai cerut înainte, deci cererea trebuie să conțină tot ce îi trebuie, inclusiv dovada că ești autentificat (de obicei un token).
  • Pentru colecții se folosește pluralul: /comenzi, /clienti, /clienti/7/comenzi.
  • Codurile de stare spun adevărul. Un răspuns 200 cu mesajul „eroare” în corp îi încurcă pe toți cei care folosesc API-ul.

Un REST API în Node.js, pas cu pas

Cel mai bun mod să înțelegi un REST API este să scrii unul mic. Codul de mai jos folosește doar Node.js, fără nicio bibliotecă instalată, și ține o listă de produse în memorie. Salvează-l ca server.js și rulează node server.js.

const http = require("http");

let produse = [
  { id: 1, nume: "Cafea boabe", pret: 89.9 },
  { id: 2, nume: "Ceai verde", pret: 14.5 }
];
let urmatorulId = 3;

function trimite(res, cod, date) {
  res.writeHead(cod, { "Content-Type": "application/json; charset=utf-8" });
  res.end(JSON.stringify(date));
}

const server = http.createServer((req, res) => {
  const parti = req.url.split("/").filter(Boolean); // "/produse/2" -> ["produse", "2"]
  if (parti[0] !== "produse") return trimite(res, 404, { eroare: "Ruta nu există" });
  const id = Number(parti[1]);

  if (req.method === "GET" && !parti[1]) return trimite(res, 200, produse);

  if (req.method === "GET") {
    const produs = produse.find(p => p.id === id);
    return produs ? trimite(res, 200, produs) : trimite(res, 404, { eroare: "Produs inexistent" });
  }

  if (req.method === "POST" && !parti[1]) {
    let corp = "";
    req.on("data", bucata => (corp += bucata));
    req.on("end", () => {
      let date;
      try {
        date = JSON.parse(corp);
      } catch {
        return trimite(res, 400, { eroare: "JSON invalid" });
      }
      if (!date.nume || typeof date.pret !== "number") {
        return trimite(res, 400, { eroare: "Trimite nume și pret (număr)" });
      }
      const nou = { id: urmatorulId++, nume: date.nume, pret: date.pret };
      produse.push(nou);
      trimite(res, 201, nou);
    });
    return;
  }

  if (req.method === "DELETE" && id) {
    produse = produse.filter(p => p.id !== id);
    res.writeHead(204);
    return res.end();
  }

  trimite(res, 405, { eroare: "Metodă nepermisă" });
});

server.listen(3000, () => console.log("API pornit pe http://localhost:3000"));

Cu serverul pornit, deschide un al doilea terminal și trimite cereri cu curl, un program care vine instalat pe Windows 10 și 11, macOS și Linux:

curl http://localhost:3000/produse
# [{"id":1,"nume":"Cafea boabe","pret":89.9},{"id":2,"nume":"Ceai verde","pret":14.5}]

curl -X POST http://localhost:3000/produse -H "Content-Type: application/json" -d '{"nume":"Miere de salcâm","pret":32}'
# {"id":3,"nume":"Miere de salcâm","pret":32}

curl -i -X DELETE http://localhost:3000/produse/1
# HTTP/1.1 204 No Content

curl http://localhost:3000/produse/1
# {"eroare":"Produs inexistent"}

Pe Windows, comanda cu POST poate da eroare în PowerShell sau în Command Prompt, pentru că ghilimelele simple se interpretează altfel. Cel mai simplu e să rulezi comenzile în Git Bash sau în terminalul din VS Code configurat pe Bash. Alternativ, folosești o unealtă cu interfață grafică, despre care găsești detalii în întrebările de la final.

Ce merită să observi în cod:

  1. http.createServer primește fiecare cerere și îți dă două obiecte: req (ce a cerut clientul) și res (prin care răspunzi).
  2. Adresa e spartă în bucăți, iar în funcție de req.method și de prezența unui id alegi ce faci. Asta se numește rutare.
  3. La POST, corpul cererii vine în bucăți, așa că îl aduni și abia la evenimentul end îl transformi din JSON în obiect.
  4. Datele greșite primesc 400, nu o eroare care oprește serverul.
  5. Funcția trimite pune mereu antetul Content-Type corect, ca diacriticele să ajungă întregi la client.

În proiecte reale nu scrii rutarea de mână, ci folosești Express sau un framework asemănător, iar produsele stau într-o bază de date, nu în memorie. Pentru partea de baze de date, începe cu articolul despre ce este SQL. Principiile din exemplul de mai sus rămân însă aceleași.

Greșeli frecvente la primul REST API

Primele bug-uri dintr-un REST API vin aproape mereu din id-uri, coduri de stare și date netrimise corect. Le-am văzut pe toate la începători, iar unele sunt greu de prins pentru că API-ul „pare să meargă”.

  • Id-uri calculate din lungimea listei. Dacă scrii id: produse.length + 1, după o ștergere două produse ajung să aibă același id. De aceea codul de mai sus folosește un contor separat, urmatorulId.
  • Uiți antetul Content-Type: application/json la cerere, iar serverul primește un corp gol sau text simplu.
  • Răspunzi cu 200 la orice. Clientul nu mai poate deosebi succesul de eroare fără să citească mesajul.
  • Pui verbe în adrese: /getProduse, /updateProdus. Metoda HTTP spune deja acțiunea.
  • Nu validezi datele. Un preț trimis ca text („32 lei”) ajunge în baza de date și strică rapoartele de la contabilitate.

Unde întâlnești REST API-uri și cine le scrie

REST API-urile sunt peste tot unde două sisteme vorbesc între ele: plata cu cardul într-un magazin online, calculul taxei de livrare la curier, prognoza meteo din telefon, sincronizarea comenzilor cu programul de facturare. Le scriu programatorii backend și le folosesc programatorii frontend și mobile, iar testerii le verifică separat de interfață.

Aproape orice aplicație pe care o folosești are în spate cel puțin un API, iar multe servicii publice își documentează API-ul ca să-l poată folosi și alți programatori. Când citești o astfel de documentație, cauți mereu aceleași lucruri: adresa de bază, resursele disponibile, metodele permise pentru fiecare, formatul datelor și felul în care te autentifici, de obicei cu o cheie sau un token trimis în antetul cererii.

Pentru un Backend Developer, construirea de REST API-uri este o mare parte din munca de zi cu zi. Dacă te atrage direcția asta, traseul Backend Developer (Node.js) pune în ordine JavaScript, Git, SQL, Node.js, TypeScript, Linux și Docker. Întrebările despre REST și HTTP apar des și la interviuri, alături de cele din articolul nostru cu întrebări tehnice comune la interviurile IT.

Întrebări frecvente

Care e diferența dintre API și REST API?

API este termenul general pentru orice interfață prin care un program îi oferă servicii altuia. REST API este un tip anume de API, construit peste HTTP, cu resurse identificate prin adrese și metode precum GET și POST. Mai există și alte stiluri, ca GraphQL sau SOAP.

Ce diferență este între PUT și PATCH?

PUT înlocuiește întreaga resursă, deci trimiți toate câmpurile, iar ce lipsește se poate pierde. PATCH modifică doar câmpurile pe care le trimiți. Pentru a schimba doar prețul unui produs, PATCH e alegerea firească; detalii despre fiecare metodă găsești în documentația MDN despre metodele HTTP.

Un REST API trebuie să folosească JSON?

Nu obligatoriu, dar aproape toate o fac. REST permite și XML sau alte formate, însă JSON e mai scurt, mai ușor de citit și e suportat nativ de JavaScript și de orice limbaj modern.

Cu ce limbaj pot scrie un REST API?

Cu aproape orice limbaj folosit pe server: JavaScript cu Node.js și Express, Python cu FastAPI sau Django, Java cu Spring Boot, C# cu ASP.NET Core, PHP cu Laravel, Go. Principiile sunt aceleași, se schimbă doar sintaxa.

Cum testez un REST API fără să scriu cod?

Cu unelte precum Postman, Insomnia sau extensia REST Client din VS Code. Alegi metoda, scrii adresa și corpul cererii, apoi vezi răspunsul și codul de stare. Pentru verificări rapide ajunge și curl din terminal.

Primul pas: rulează API-ul și adaugă PATCH

Pornește serverul de mai sus, trimite cele patru cereri cu curl, apoi adaugă singur ruta PATCH /produse/:id care modifică doar prețul. Dacă vrei să construiești API-uri cu Express, autentificare și baze de date, cu exerciții verificate prin cereri HTTP reale trimise către serverul tău, începe cu primele 15 lecții gratuite din cursul de Node.js.

Logo Curs Node.js Interactiv · 15 lecții gratuite

Curs Node.js

Node.js pentru începători: servere, API-uri REST și Express

Începe gratuit

Citește și

Primul tău program e la 5 minute distanță.

Creează-ți contul gratuit și începe primele 15 lecții. Fără card, fără instalări.

Începe gratuit