Patch verb - Patch verb
În calcul, metoda PATCH este o metodă de solicitare acceptată de protocolul Hypertext Transfer Protocol (HTTP) pentru efectuarea modificărilor parțiale la o resursă existentă. Metoda PATCH oferă o entitate care conține o listă de modificări care trebuie aplicate resursei solicitate utilizând identificatorul HTTP Uniform Resource Identifier (URI). Lista modificărilor este furnizată sub forma unui document PATCH. Dacă resursa solicitată nu există, atunci serverul poate crea resursa în funcție de tipul de suport de document PATCH și permisiuni. Modificările descrise în documentul PATCH trebuie să fie semantic bine definite, dar pot avea un tip de suport diferit de cel al resursei care este patch. Cadrele precum XML , JSON pot fi utilizate în descrierea modificărilor din documentul PATCH.
Istoria PATCH-ului
Conform semanticii definite în protocolul HTTP , metodele GET , PUT și POST trebuie să utilizeze o reprezentare completă a resursei. Metoda PUT care poate fi utilizată pentru crearea sau înlocuirea resurselor este idempotentă și poate fi utilizată doar pentru actualizări complete. Formularele de editare utilizate în aplicația convențională Ruby on Rails trebuie să creeze resurse noi prin aplicarea actualizărilor parțiale unei resurse părinte. Datorită acestei cerințe, metoda PATCH a fost adăugată la protocolul HTTP în 2010.
PUT vs PATCH vs POST
HTTP este baza comunicării datelor pentru World Wide Web . Este un protocol de solicitare-răspuns care ajută utilizatorii să comunice cu serverul pentru a efectua operații CRUD . HTTP acceptă o serie de metode de solicitare, cum ar fi PUT , POST și PATCH pentru a crea sau actualiza resurse.
Principala diferență între metoda PUT și PATCH este că metoda PUT folosește URI-ul de solicitare pentru a furniza o versiune modificată a resursei solicitate care înlocuiește versiunea originală a resursei, în timp ce metoda PATCH furnizează un set de instrucțiuni pentru a modifica resursa. Dacă documentul PATCH este mai mare decât dimensiunea noii versiuni a resursei trimise prin metoda PUT , atunci este preferată metoda PUT .
Metoda POST poate fi utilizată pentru trimiterea actualizărilor parțiale către o resursă. Principala diferență între metodele POST și PATCH este că metoda POST poate fi utilizată numai atunci când este scrisă pentru a sprijini aplicațiile sau aplicațiile acceptă semantica acesteia, în timp ce metoda PATCH poate fi utilizată într-un mod generic și nu necesită suport pentru aplicație. Dacă rezultatul utilizării metodei PATCH nu este cunoscut, atunci este preferată metoda POST.
Corectarea resurselor
Metoda PATCH este atomică . Fie toate modificările specificate de metoda PATCH sunt aplicate, fie niciuna dintre modificări nu este aplicată de server. Există multe modalități de a verifica dacă un patch a fost aplicat cu succes. De exemplu, utilitarul „diff” poate fi aplicat versiunii mai vechi și versiunii mai noi a unui fișier pentru a găsi diferențele dintre ele.
Un răspuns PATCH în cache este considerat învechit. Poate fi utilizat numai pentru solicitările GET și HEAD care pot urma cererea PATCH.
Anteturile entității din documentul PATCH sunt aplicabile numai documentului PATCH și nu pot fi aplicate resursei solicitate.
Nu există un format standard pentru documentul PATCH și este diferit pentru diferite tipuri de resurse. Serverul trebuie să verifice dacă documentul PATCH primit este adecvat pentru resursa solicitată.
Un document JSON Patch ar arăta ca.
{ "op": "add", "path": "/count", "value": 1 }
"op" reprezintă operația efectuată asupra resursei. „cale” reprezintă resursa modificată. „valoare” reprezintă suma adăugată la resursa existentă. Înainte de a aplica modificările în documentul PATCH, serverul trebuie să verifice dacă documentul PATCH primit este adecvat pentru resursa solicitată. Dacă cererea PATCH reușește, atunci returnează un răspuns 204 .
Un document XML PATCH ar arăta ca.
<add sel="doc/user[@email='[email protected]']" type="@address">
ABC Road
</add>
Elementul <utilizator> este localizat utilizând atributul „e-mail”. Un element nou „adresă” cu valoarea „ABC Road” este adăugat elementului <utilizator>.
Exemplu
Un exemplu simplu de cerere PATCH
PATCH /example.txt HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "c0b42b66e" Content-Length: 120
[changes]
[modificări] este documentul de corecție care conține toate modificările care trebuie făcute pe resursa example.txt
Răspuns PATCH de succes la fișierul text existent:
HTTP/1.1 204 No Content Content-Location: /example.txt ETag: "c0b42b66f"
Răspunsul 204 înseamnă că solicitarea a fost procesată cu succes.
Compensări între PUT și PATCH
Utilizarea metodei PUT consumă mai multă lățime de bandă în comparație cu metoda PATCH atunci când trebuie aplicate doar câteva modificări unei resurse. Dar când se utilizează metoda PATCH, aceasta implică de obicei preluarea resursei de pe server, compararea fișierelor originale și cele noi, crearea și trimiterea unui fișier diff. Pe partea serverului, serverul trebuie să citească fișierul diff și să facă modificările. Aceasta implică o mulțime de cheltuieli generale în comparație cu metoda PUT. Pe de altă parte, metoda PUT necesită efectuarea unui GET înainte de PUT și este dificil să vă asigurați că resursa nu este modificată între solicitările GET și PUT .
Prudență
Metoda PATCH nu este „sigură” în sensul RFC 2616: poate modifica resursele, nu neapărat limitate la cele menționate în URI .
Metoda PATCH nu este idempotentă . Poate fi făcut idempotent utilizând o cerere condiționată. Când un client face o cerere condiționată către o resursă, solicitarea reușește numai dacă resursa nu a fost actualizată de la ultima accesare a resursei de către client. Acest lucru ajută și la prevenirea corupției resursei, deoarece unele actualizări ale unei resurse pot fi efectuate numai începând cu un anumit punct de bază.
Eroare de manipulare
O cerere PATCH poate eșua dacă apare oricare dintre următoarele erori:
Document de corecție malformat
Serverul returnează un răspuns 400 (Cerere greșită) dacă documentul PATCH nu este formatat după cum este necesar.
Document de patch neacceptat
Serverul returnează un răspuns 415 ( Tip suport media neacceptat ) cu un antet de răspuns Accept-Patch care conține tipuri de suport acceptate atunci când clientul trimite un document de corecție neacceptat. Aceasta informează clientul că documentul PATCH trimis de client nu poate fi aplicat resursei solicitate.
Cerere neprocesabilă
Serverul returnează un răspuns 422 (Entitate neprocesabilă) atunci când serverul înțelege documentul PATCH, dar nu este în măsură să modifice resursa solicitată, fie din cauză că resursa devine invalidă, fie rezultă într-o altă stare de eroare.
Resursa nu a fost găsită
Serverul returnează un răspuns 404 (Not Found) atunci când documentul PATCH nu poate fi aplicat unei resurse inexistente.
Stare conflictuală
Serverul returnează un răspuns 409 (Conflict) atunci când serverul nu poate aplica un patch pentru starea curentă a resursei.
Modificare conflictuală
Serverul returnează un răspuns 412 (Precondition Failed) când precondiția furnizată de client utilizând antetul If-Match sau If-Unmodified-Since eșuează. Dacă nu este furnizată nicio condiție prealabilă și există o modificare conflictuală, atunci serverul returnează un răspuns 409 (Conflict).
Modificare concurentă
Serverul returnează un răspuns 409 (Conflict) dacă solicitările PATCH către o anumită resursă trebuie aplicate într-o anumită ordine și serverul nu este capabil să gestioneze cererile PATCH concurente.
Considerații de securitate
Solicitarea PATCH trebuie să utilizeze mecanisme precum cereri condiționate care utilizează Etags și antetul cererii If-Match pentru a se asigura că datele nu sunt corupte în timpul corecției. În caz de eșec al unei cereri PATCH sau eșec al canalului sau al unui timeout, clientul poate utiliza o cerere GET pentru a verifica starea resursei. Serverul trebuie să se asigure că clienții rău intenționați nu folosesc metoda PATCH pentru consumul de resurse excesive ale serverului.
