Apif-urile REST vă permit să dezvoltați orice tip de aplicație web cu toate operațiile CRUD (creare, recuperare, actualizare, ștergere) posibile. Orientările REST sugerează utilizarea unei metode HTTP specifice pe un anumit tip de apel efectuat către server (deși, din punct de vedere tehnic, este posibil să se încalce această orientare, totuși este foarte descurajat).
Utilizați informațiile date mai jos pentru a găsi o metodă HTTP adecvată pentru acțiunea efectuată de API.
Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary
HTTP GET
Utilizați cererile GET doar pentru a prelua reprezentarea/informațiile resurselor – și nu pentru a le modifica în vreun fel. Deoarece cererile GET nu modifică starea resursei, se spune că acestea sunt metode sigure. În plus, API-urile GET ar trebui să fie idempotente, ceea ce înseamnă că efectuarea mai multor cereri identice trebuie să producă același rezultat de fiecare dată până când o altă API (POST sau PUT) a modificat starea resursei pe server.
Dacă Request-URI se referă la un proces de producere a datelor, datele produse sunt cele care trebuie returnate ca entitate în răspuns și nu textul sursă al procesului, cu excepția cazului în care acest text se întâmplă să fie rezultatul procesului.
Pentru orice API HTTP GET dată, dacă resursa este găsită pe server, atunci trebuie să returneze codul de răspuns HTTP 200 (OK) – împreună cu corpul răspunsului, care este, de obicei, fie conținut XML, fie JSON (datorită naturii lor independente de platformă).
În cazul în care resursa NU este găsită pe server, atunci trebuie să returneze codul de răspuns HTTP 404 (NOT FOUND). În mod similar, în cazul în care se stabilește că cererea GET în sine nu este corect formată atunci serverul va returna codul de răspuns HTTP 400 (BAD REQUEST).
Exemplu de URI-uri de cerere
- HTTP GET http://www.appdomain.com/users
- HTTP GET http://www.appdomain.com/users?size=20&page=5
- HTTP GET http://www.appdomain.com/users/123
- HTTP GET http://www.appdomain.com/users/123/adresa
HTTP POST
Utilizați API-urile POST pentru a crea noi resurse subordonate, de ex, un fișier este subordonat unui director care îl conține sau un rând este subordonat unui tabel de bază de date. Atunci când se vorbește strict în termeni de REST, metodele POST sunt utilizate pentru a crea o nouă resursă în colecția de resurse.
În mod normal, dacă o resursă a fost creată pe serverul de origine, răspunsul TREBUIE să aibă codul de răspuns HTTP 201 (Created) și să conțină o entitate care descrie starea cererii și se referă la noua resursă, precum și un antet Location.
De multe ori, este posibil ca acțiunea efectuată prin metoda POST să nu aibă ca rezultat o resursă care poate fi identificată printr-un URI. În acest caz, fie codul de răspuns HTTP 200 (OK), fie 204 (No Content) este starea de răspuns adecvată.
Răspunsurile la această metodă nu pot fi stocate în memoria cache, cu excepția cazului în care răspunsul include câmpurile corespunzătoare de antet Cache-Control sau Expires.
Rețineți că POST nu este nici sigură, nici idempotentă, iar invocarea a două cereri POST identice va avea ca rezultat două resurse diferite care conțin aceleași informații (cu excepția id-urilor de resurse).
Exemplu de URI-uri de cerere
- HTTP POST http://www.appdomain.com/users
- HTTP POST http://www.appdomain.com/users/123/accounts
HTTP PUT
Utilizați API-urile PUT în primul rând pentru a actualiza resursa existentă (dacă resursa nu există, atunci API poate decide să creeze sau nu o nouă resursă). Dacă o nouă resursă a fost creată de către API PUT, serverul de origine TREBUIE să informeze agentul utilizator prin intermediul codului de răspuns HTTP 201 (Created) de răspuns, iar dacă o resursă existentă este modificată, ar trebui să se trimită codurile de răspuns 200 (OK) sau 204 (No Content) pentru a indica finalizarea cu succes a cererii.
Dacă cererea trece printr-o memorie cache și Request-URI identifică una sau mai multe entități aflate în prezent în memoria cache, aceste intrări TREBUIE să fie tratate ca fiind vechi. Răspunsurile la această metodă nu pot fi stocate în memoria cache.
Exemplu de URI-uri de cerere
- HTTP PUT http://www.appdomain.com/users/123
- HTTP PUT http://www.appdomain.com/users/123/accounts/456
HTTP DELETE
După cum îi spune și numele, API-urile DELETE sunt folosite pentru a șterge resurse (identificate prin Request-URI).
Un răspuns de succes al cererilor DELETE TREBUIE să fie răspunsul HTTP code 200 (OK) dacă răspunsul include o entitate care descrie starea, 202 (Accepted) dacă acțiunea a fost pusă în coadă sau 204 (No Content) dacă acțiunea a fost efectuată, dar răspunsul nu include o entitate.
Operațiile DELETE sunt idempotente. Dacă ELIMINAȚI o resursă, aceasta este eliminată din colecția de resurse. Apelarea repetată a API DELETE pe acea resursă nu va schimba rezultatul – cu toate acestea, apelarea DELETE pe o resursă a doua oară va returna un 404 (NOT FOUND), deoarece aceasta a fost deja eliminată. Unii ar putea susține că acest lucru face ca metoda DELETE să fie neidempotentă. Este o chestiune de discuție și de opinie personală.
Dacă cererea trece printr-un cache și Request-URI identifică una sau mai multe entități aflate în prezent în cache, aceste intrări TREBUIE să fie tratate ca fiind vechi. Răspunsurile la această metodă nu pot fi stocate în memoria cache.
Exemplu de URI-uri de cerere
- HTTP DELETE http://www.appdomain.com/users/123
- HTTP DELETE http://www.appdomain.com/users/123/accounts/456
HTTP PATCH
Cererile HTTP PATCH au rolul de a face o actualizare parțială a unei resurse. Dacă vedeți că solicitările PUT modifică de asemenea o entitate de resursă, deci pentru a fi mai clar – metoda PATCH este alegerea corectă pentru actualizarea parțială a unei resurse existente, iar PUT ar trebui folosită numai dacă înlocuiți o resursă în întregime.
Rețineți că există unele provocări dacă decideți să folosiți API-urile PATCH în aplicația dumneavoastră:
- Suportul pentru PATCH în browsere, servere și cadre de aplicații web nu este universal. IE8, PHP, Tomcat, Django și o mulțime de alte software-uri au un suport lipsă sau rupt pentru acesta.
- Request payload al unei cereri PATCH nu este direct ca și în cazul cererii PUT. de ex.
HTTP GET /users/1produce răspunsul de mai jos:
{id: 1, username: 'admin', email: ''}Un exemplu de cerere de patch pentru actualizarea e-mailului va fi astfel:
HTTP PATCH /users/1” }
]
Pot exista următoarele operațiuni posibile conform specificațiilor HTTP.
},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]
Metoda PATCH nu este un înlocuitor al metodelor POST sau PUT. Ea aplică un delta (diff) mai degrabă decât să înlocuiască întreaga resursă.
Rezumat al metodelor HTTP pentru API-urile RESTful
Tabelul de mai jos rezumă utilizarea metodelor HTTP discutate mai sus.
| Metoda HTTP | CRUD | Întreaga colecție (de ex. /users) | Element specific (de exemplu /users/123) |
|---|---|---|---|
| POST | Create | 201 (Created), antet ‘Location’ cu link către /users/{id} care conține noul ID. | Evitați utilizarea POST pe o singură resursă |
| GET | Read | 200 (OK), listă de utilizatori. Utilizați paginarea, sortarea și filtrarea pentru a naviga în listele mari. | 200 (OK), utilizator unic. 404 (Not Found), dacă ID-ul nu este găsit sau este invalid. |
| PUT | Update/Replace | 405 (Metoda nu este permisă), dacă nu doriți să actualizați fiecare resursă din întreaga colecție de resurse. | 200 (OK) sau 204 (Fără conținut). Utilizați 404 (Not Found), dacă ID-ul nu este găsit sau nu este valid. |
| PATCH | Partial Update/Modify | 405 (Metoda nu este permisă), cu excepția cazului în care doriți să modificați colecția în sine. | 200 (OK) sau 204 (No Content). Folosiți 404 (Not Found), dacă ID-ul nu este găsit sau nu este valid. |
| DELETE | Delete | 405 (Metoda nu este permisă), cu excepția cazului în care doriți să ștergeți întreaga colecție – utilizați cu prudență. | 200 (OK). 404 (Not Found), în cazul în care ID-ul nu este găsit sau nu este valid. |
Glosar
Metode sigure
Conform specificațiilor HTTP, metodele GET și HEAD ar trebui utilizate numai pentru recuperarea reprezentărilor resurselor – și nu actualizează/șterge resursa de pe server. Se spune că ambele metode sunt considerate „sigure”.
Aceasta permite agenților de utilizator să reprezinte alte metode, cum ar fi POST, PUT și DELETE, într-un mod unic, astfel încât utilizatorul să fie conștient de faptul că este solicitată o acțiune posibil nesigură – iar acestea pot actualiza/șterge resursa de pe server și, prin urmare, trebuie utilizate cu atenție.
Metode idempotente
Termenul idempotent este utilizat în mod mai cuprinzător pentru a descrie o operație care va produce aceleași rezultate dacă este executată o dată sau de mai multe ori. Idempotența este o proprietate la îndemână în multe situații, deoarece înseamnă că o operație poate fi repetată sau reluată ori de câte ori este necesar, fără a provoca efecte nedorite. În cazul operațiilor neidempotente, este posibil ca algoritmul să fie nevoit să urmărească dacă operația a fost deja efectuată sau nu.
În specificația HTTP, metodele GET, HEAD, PUT și DELETE sunt declarate metode idempotente. Alte metode OPTIONS și TRACE NU TREBUIE să aibă efecte secundare, deci ambele sunt, de asemenea, idempotente în mod inerent.