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ă REST | Metodă | Înțeles |
|---|---|---|
| /products | GET | lista de produse |
| /products/7 | GET | produsul cu id 7 |
| /cart/items | POST | adaugă un produs în coș |
| /cart/items/7 | DELETE | scoate produsul 7 din coș |
| /orders | GET | comenzile mele |
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:
| Metode | Endpoint | Descriere |
|---|---|---|
| GET | /health | Starea serviciului |
| POST | /auth/login | Autentificare cu email și parolă |
| POST | /auth/register | Cont nou |
| GET | /auth/me | Utilizatorul autentificat |
| GET, POST | /products | Lista 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 | /categories | Categoriile |
| GET | /search | Căutare (maximum 10 cereri pe minut) |
| GET, DELETE | /cart | Coșul meu / Golește coșul |
| POST | /cart/items | Adaugă în coș |
| PATCH, DELETE | /cart/items/{productId} | Schimbă cantitatea / Scoate din coș |
| POST | /cart/coupon | Aplică un cupon (REDUCERE10: -10% de la 100 lei) |
| GET, POST | /orders | Comenzile mele / Plasează comanda din coș |
| GET | /orders/{id} | O comandă |
| POST | /orders/{id}/cancel | Anulează comanda (doar pending) |
| GET | /users | Utilizatorii (admin) |
| GET | /users/{id} | Un utilizator (admin) |
| GET | /reports/sales | Raport de vânzări (cheie API) |
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
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).
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.
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.
