URL-ul: protocol, host, cale și parametri de query
Un URL nu este doar o adresă lungă: fiecare bucată din el are un rol precis. În această lecție desfaci un URL în părți, înveți ce sunt parametrii de query și cum îi adaugi comod din tabul Params al Postman, ca să filtrezi lista de produse a magazinului.
Un URL, bucată cu bucată
Ia adresa de mai jos. Pare un singur șir de caractere, dar serverul o citește în bucăți:
https://api.magazin.test/products?category=carti&limit=3
| Bucata | Valoarea | Ce înseamnă |
|---|---|---|
| protocolul | https:// | cum se vorbește cu serverul; https = conexiune criptată |
| host-ul | api.magazin.test | numele serverului, ca numele unei clădiri |
| calea (path) | /products | resursa de pe server, ca numărul apartamentului |
| query-ul | ?category=carti&limit=3 | opțiuni pentru cerere: ce filtrezi, câte rezultate vrei |
Partea care începe la ? se numește query string. Ea conține parametri de query sub forma cheie=valoare, despărțiți prin &. Aici sunt doi: category cu valoarea carti și limit cu valoarea 3.
Primul parametru vine după ?, iar următorii după &. Dacă scrii ?category=carti?limit=3, serverul vede un singur parametru, cu o valoare ciudată, carti?limit=3.
Ce parametri acceptă magazinul
Fiecare API își documentează parametrii. Pentru GET /products, magazinul demo acceptă:
| Parametru | Exemplu | Efect |
|---|---|---|
| page | page=2 | pagina de rezultate (implicit 1) |
| limit | limit=5 | câte produse pe pagină (între 1 și 50, implicit 10) |
| category | category=carti | doar produsele dintr-o categorie |
| q | q=mouse | caută după nume |
| minPrice, maxPrice | maxPrice=100 | interval de preț |
| sort | sort=price sau sort=-price | ordonare după preț sau nume; - înseamnă descrescător |
Cu doi parametri ceri doar cărțile, câte două pe pagină:
GET https://api.magazin.test/products?category=carti&limit=2
200 OK
{
"data": [
{
"id": 16,
"name": "Testarea software pe înțelesul tuturor",
"sku": "TESTAREA-SOF-016",
"price": 79,
"currency": "RON",
"category": "carti",
"stock": 50,
"rating": 4.9,
"active": true,
"createdAt": "2026-02-19T10:00:00.000Z"
},
{
"id": 17,
"name": "Primii pași în programare",
"sku": "PRIMII-PASI--017",
"price": 65,
"currency": "RON",
"category": "carti",
"stock": 35,
"rating": 4.7,
"active": true,
"createdAt": "2026-02-22T10:00:00.000Z"
}
],
"page": 1,
"limit": 2,
"total": 5,
"totalPages": 3
}Uită-te la ultimele câmpuri: total spune câte cărți are magazinul în total (5), limit câte ai primit pe pagină, iar totalPages câte pagini sunt.
Tabul Params: parametrii ca tabel
Scrisul de mână al parametrilor în URL e ușor de greșit. Postman are sub URL tabul Params, un tabel cu coloanele Key și Value. Tabelul și URL-ul sunt sincronizate: ce scrii într-unul apare imediat în celălalt.
Fiecare rând are în stânga o bifă. Dacă o debifezi, parametrul rămâne în tabel, dar dispare din URL și nu mai este trimis. E foarte util la testare: compari rapid răspunsul cu și fără un filtru, fără să ștergi și să rescrii nimic.
Postman codifică singur caracterele speciale din valori. De exemplu, un spațiu devine %20 în URL. Tu scrii valoarea normal în tabel.
Când un parametru e greșit
Un API bine făcut nu ghicește ce ai vrut. Dacă trimiți o valoare invalidă, răspunde cu 400 Bad Request și îți explică problema:
GET https://api.magazin.test/products?limit=abc
400 Bad Request
{
"error": "bad_request",
"message": "Parametrul limit trebuie să fie între 1 și 50."
}Asta e o idee de caz de test valoros: pentru fiecare parametru încerci și valori greșite (text în loc de număr, număr negativ, 0, 51) și verifici că serverul le refuză frumos, cu 400, nu cu o eroare 500 sau cu date greșite.
Greșeli frecvente
- Spații sau majuscule în cheie. Category nu este același lucru cu category pentru majoritatea serverelor.
- Diacritice în valori de filtru. Categoria se numește carti în API, chiar dacă pe site apare „Cărți”. Citește documentația pentru valorile exacte.
- Uiți că un parametru e debifat. Dacă răspunsul pare nefiltrat, verifică bifele din Params.
- Confunzi calea cu query-ul. /products/7 cere produsul cu id 7 (în cale), pe când /products?id=7 este un filtru, pe care acest API nu îl are.
Din aplicațiile reale
- Magazinele online: când bifezi „Cărți” și „sub 100 lei” în stânga paginii, site-ul trimite un GET cu parametri ca category și maxPrice.
- Căutarea de zboruri: orașul de plecare, data și numărul de pasageri pleacă de obicei ca parametri de query.
Un client vrea să vadă doar cărțile din magazin, câte trei pe pagină. Construiește cererea folosind tabul Params, nu scriind parametrii de mână.
- Scrie în URL https://api.magazin.test/products cu metoda GET.
- În tabul Params adaugă category = carti și limit = 3.
- Trimite cererea și verifică în body că total este 5 și că ai primit 3 produse.
Soluția exercițiului
1. URL: https://api.magazin.test/products, metoda GET. 2. Params: rândul 1 Key category, Value carti; rândul 2 Key limit, Value 3. URL-ul devine https://api.magazin.test/products?category=carti&limit=3. 3. Send: primești 200 OK, 3 cărți în data și "total": 5.
