...
← Curs API Testing cu Postman: toate lecțiile
Lecția 8 · REST

REST: resurse, endpoint-uri și documentație

Majoritatea API-urilor pe care le vei testa sunt API-uri REST. Ele urmează câteva reguli simple care fac adresele previzibile: dacă ai înțeles un endpoint, le ghicești pe celelalte. În această lecție înveți aceste reguli și citești lista de endpoint-uri a magazinului din documentația lui.

Resurse și metode: substantive și verbe

REST (Representational State Transfer) este un stil de a construi API-uri. Ideea principală: adresa (URL-ul) numește un lucru, iar metoda HTTP spune ce faci cu el. Lucrurile se numesc resurse: produse, coșul, comenzi, utilizatori.

Pe scurt: în cale pui substantive, iar metoda e verbul. Un API REST nu are adrese ca /getProducts sau /deleteCartItem; are /products și /cart/items/7, iar verbul vine din metodă.

Adresă RESTMetodăÎnțeles
/productsGETlista de produse
/products/7GETprodusul cu id 7
/cart/itemsPOSTadaugă un produs în coș
/cart/items/7DELETEscoate produsul 7 din coș
/ordersGETcomenzile mele
Ce este un endpoint

Un endpoint este combinația dintre o metodă și o cale, de exemplu GET /products/7. Când cineva spune „testează endpoint-ul de login”, se referă la POST /auth/login.

Colecție și element

În REST, fiecare resursă apare de obicei în două forme:

  • colecția: /products, toate produsele (o listă);
  • elementul: /products/7, un singur produs, identificat prin id în cale.
GET https://api.magazin.test/products/7
200 OK
{
  "id": 7,
  "name": "Mouse wireless",
  "sku": "MOUSE-WIRELE-007",
  "price": 89,
  "currency": "RON",
  "category": "accesorii",
  "stock": 120,
  "rating": 4.3,
  "active": true,
  "createdAt": "2026-01-23T10:00:00.000Z"
}

Pe colecție poți cere liste cu filtre și ordonare, prin parametri de query. De exemplu, cel mai scump produs din magazin: ordonezi descrescător după preț (sort=-price) și ceri un singur rezultat (limit=1):

GET https://api.magazin.test/products?sort=-price&limit=1
200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Laptop Gaming X17",
      "sku": "LAPTOP-GAMIN-002",
      "price": 6299,
      "currency": "RON",
      "category": "laptopuri",
      "stock": 4,
      "rating": 4.8,
      "active": true,
      "createdAt": "2026-01-08T10:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 30,
  "totalPages": 30
}

Resursele se pot și imbrica: /cart/items sunt produsele din coș, iar /orders/1001/cancel este acțiunea de anulare a comenzii 1001.

Documentația API-ului

Ca tester nu ghicești endpoint-urile: le citești din documentație. Multe echipe o scriu în formatul standard OpenAPI (numit și Swagger), un fișier JSON care descrie fiecare endpoint, parametrii lui și răspunsurile posibile. Magazinul demo își publică documentația la /openapi.json:

GET https://api.magazin.test/openapi.json
200 OK
{
  "openapi": "3.0.3",
  "info": {
    "title": "Magazinul Demo API",
    "version": "1.4.0",
    "description": "API-ul de exercițiu al cursului de API Testing. Autentificare: POST /auth/login → token (Bearer)."
  },
  ...
}

Fișierul complet are peste 10 KB. Partea cea mai utilă este paths, lista tuturor endpoint-urilor. Pe scurt, arată așa:

MetodeEndpointDescriere
GET/healthStarea serviciului
POST/auth/loginAutentificare cu email și parolă
POST/auth/registerCont nou
GET/auth/meUtilizatorul autentificat
GET, POST/productsLista de produse (paginată) / Adaugă un produs (doar admin)
GET, PUT, PATCH, DELETE/products/{id}Un produs / Înlocuiește produsul (admin) / Modifică câmpuri (admin) / Șterge produsul (admin)
GET/categoriesCategoriile
GET/searchCăutare (maximum 10 cereri pe minut)
GET, DELETE/cartCoșul meu / Golește coșul
POST/cart/itemsAdaugă în coș
PATCH, DELETE/cart/items/{productId}Schimbă cantitatea / Scoate din coș
POST/cart/couponAplică un cupon (REDUCERE10: -10% de la 100 lei)
GET, POST/ordersComenzile mele / Plasează comanda din coș
GET/orders/{id}O comandă
POST/orders/{id}/cancelAnulează comanda (doar pending)
GET/usersUtilizatorii (admin)
GET/users/{id}Un utilizator (admin)
GET/reports/salesRaport de vânzări (cheie API)
Bine de știut

Postman poate importa un fișier OpenAPI și creează singur toate cererile. Vei face asta în lecția 61. Deocamdată folosește documentația ca pe o listă de lucru: fiecare rând este cel puțin un caz de test.

Cum gândește un tester un API REST

1
Citește în documentație ce endpoint-uri există și ce face fiecare.
2
Pentru fiecare endpoint încearcă întâi „drumul fericit”: o cerere corectă, cu răspunsul promis (200, 201...).
3
Apoi încearcă erorile: un id care nu există (404), date lipsă (422), fără autentificare (401).
4
Compară răspunsul cu documentația: aceleași câmpuri, aceleași tipuri, același cod de status.

Când răspunsul nu se potrivește cu documentația, fie API-ul are un bug, fie documentația e depășită. În ambele cazuri merită raportat.

Greșeli frecvente

  • Pluralul uitat. Calea este /products/7, nu /product/7. O literă lipsă dă 404.
  • Id-ul pus în query. /products?id=7 nu e același lucru cu /products/7.
  • Slash la final. Unele servere tratează /products/ diferit de /products. Folosește forma din documentație.
  • Verbe în cale. Dacă vezi /deleteProduct?id=7 într-un API care se declară REST, merită o întrebare la echipă.

Din aplicațiile reale

  • Aplicația de livrări: GET /restaurants, GET /restaurants/42/menu, POST /orders.
  • Un API de bibliotecă: GET /books?author=Creanga, POST /loans, DELETE /loans/15 (returnezi cartea).
Exercițiul tău

Folosește regulile REST ca să citești un singur produs și apoi să găsești cel mai scump produs din magazin.

  • Trimite GET https://api.magazin.test/products/7 (elementul cu id 7).
  • Trimite GET https://api.magazin.test/products cu parametrii sort=-price și limit=1.
  • Citește în al doilea răspuns numele și prețul celui mai scump produs.
Parametrii îi poți scrie direct în URL (?sort=-price&limit=1) sau în tabul Params.

Soluția exercițiului

1. GET https://api.magazin.test/products/7 → 200 OK, „Mouse wireless”, 89 lei.
2. GET https://api.magazin.test/products?sort=-price&limit=1 → 200 OK; în data este un singur produs, „Laptop Gaming X17”, 6299 lei.
Excelent! Continuă cu lecția următoare →
PostmanPostman
VerificareSe încarcă...
Mediul de lucru se încarcă. Poți citi lecția între timp.
Parcursul tău Primii pași cu API-uri și Postman Lecția 8 · REST: resurse, endpoint-uri și documentație
Progres 0% 0 din 12
Lecția curentă 8 / 10 Rest