Patch verb - Patch verb
I computing er PATCH- metoden en anmodningsmetode understøttet af HTTP- protokollen ( Hypertext Transfer Protocol ) til delvis ændring af en eksisterende ressource. PATCH-metoden giver en enhed, der indeholder en liste over ændringer, der skal anvendes på den anmodede ressource ved hjælp af HTTP Uniform Resource Identifier (URI). Listen over ændringer leveres i form af et PATCH-dokument. Hvis den ønskede ressource ikke findes, kan serveren muligvis oprette ressourcen afhængigt af PATCH-dokumentets medietype og tilladelser. Ændringerne beskrevet i PATCH-dokumentet skal være semantisk veldefineret, men kan have en anden medietype end den ressource, der patches. Rammer som XML , JSON kan bruges til at beskrive ændringerne i PATCH-dokumentet.
PATCHs historie
I henhold til semantikken defineret i HTTP- protokollen skal GET- , PUT- og POST- metoderne bruge en fuld repræsentation af ressourcen. PUT-metoden, som kan bruges til oprettelse eller udskiftning af ressourcer, er idempotent og kan kun bruges til fulde opdateringer. Redigeringsformularerne, der bruges i konventionel Ruby on Rails- applikation, skal oprette nye ressourcer ved at anvende delvise opdateringer til en overordnet ressource. På grund af dette krav blev PATCH-metoden tilføjet til HTTP-protokollen i 2010.
PUT vs PATCH vs POST
HTTP er grundlaget for datakommunikation til World Wide Web . Det er en anmodning-svar- protokol, som hjælper brugerne med at kommunikere med serveren til at udføre CRUD- operationer. HTTP understøtter en række anmodningsmetoder såsom PUT , POST og PATCH for at oprette eller opdatere ressourcer.
Hovedforskellen mellem PUT- og PATCH-metoden er, at PUT-metoden bruger URI- anmodningen til at levere en ændret version af den anmodede ressource, der erstatter den oprindelige version af ressourcen, mens PATCH-metoden leverer et sæt instruktioner til at ændre ressourcen. Hvis plasteret dokumentet er større end størrelsen af den nye version af ressourcen sendt af PUT metoden så PUT metode foretrækkes.
POST-metoden kan bruges til at sende delvise opdateringer til en ressource. Hovedforskellen mellem POST- og PATCH-metoderne er, at POST-metoden kun kan bruges, når den er skrevet til at understøtte applikationerne, eller hvis applikationerne understøtter dens semantik, mens PATCH-metoden kan bruges på en generisk måde og ikke kræver applikationssupport. Hvis resultatet af brugen af PATCH-metoden ikke er kendt, foretrækkes POST-metoden.
Patching ressourcer
PATCH-metoden er atomær . Enten anvendes alle de ændringer, der er angivet med PATCH-metoden, eller ingen af ændringerne anvendes af serveren. Der er mange måder at kontrollere, om en patch blev anvendt med succes. For eksempel kan 'diff' hjælpeprogrammet anvendes til den ældre version og nyere version af en fil for at finde forskellene mellem dem.
Et cachelagret PATCH-svar betragtes som forældet. Det kan kun bruges til GET- og HEAD-anmodninger, der kan følge PATCH-anmodningen.
Enhedsoverskrifterne i PATCH-dokumentet gælder kun for PATCH-dokumentet og kan ikke anvendes på den anmodede ressource.
Der er ikke noget standardformat til PATCH-dokumentet, og det er forskelligt for forskellige typer ressourcer. Serveren skal kontrollere, om det modtagne PATCH-dokument er passende for den ønskede ressource.
Et JSON Patch- dokument vil se ud
{ "op": "add", "path": "/count", "value": 1 }
"op" repræsenterer den handling, der udføres på ressourcen. "sti" repræsenterer den ressource, der ændres. "værdi" repræsenterer det beløb, der føjes til den eksisterende ressource. Før ændringerne i PATCH-dokumentet anvendes, skal serveren kontrollere, om det modtagne PATCH-dokument er passende for den ønskede ressource. Hvis PATCH-anmodningen lykkes, returnerer den et 204- svar.
Et XML PATCH-dokument vil se ud
<add sel="doc/user[@email='xyz@abc.com']" type="@address">
ABC Road
</add>
Elementet <bruger> findes ved hjælp af attributten 'e-mail'. En ny attribut 'adresse' med værdien "ABC Road" føjes til elementet <bruger>.
Eksempel
Et simpelt eksempel på PATCH-anmodning
PATCH /example.txt HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "c0b42b66e" Content-Length: 120
[changes]
[ændringer] er patch-dokumentet, der indeholder alle de ændringer, der skal foretages på ressourceeksemplet.txt
Vellykket PATCH-svar på eksisterende tekstfil:
HTTP/1.1 204 No Content Content-Location: /example.txt ETag: "c0b42b66f"
Svaret 204 betyder, at anmodningen blev behandlet med succes.
Afvejninger mellem PUT og PATCH
Brug af PUT- metoden bruger mere båndbredde sammenlignet med PATCH-metoden, når kun et par ændringer skal anvendes på en ressource. Men når PATCH-metoden bruges, indebærer det normalt at hente ressourcen fra serveren, sammenligne de originale og nye filer, oprette og sende en diff-fil. På serversiden skal serveren læse diff-filen og foretage ændringer. Dette involverer meget overhead i forhold til PUT-metoden. På den anden side kræver PUT- metoden, at der udføres en GET før PUT, og det er vanskeligt at sikre, at ressourcen ikke ændres mellem GET- og PUT- anmodningerne.
Advarsel
PATCH-metoden er ikke "sikker" i betydningen RFC 2616: den kan ændre ressourcer, ikke nødvendigvis begrænset til dem, der er nævnt i URI .
PATCH-metoden er ikke ledig . Det kan gøres ledigt ved hjælp af en betinget anmodning. Når en klient fremsætter en betinget anmodning til en ressource, lykkes anmodningen kun, hvis ressourcen ikke er opdateret, siden klienten sidst fik adgang til den ressource. Dette hjælper også med at forhindre korruption af ressourcen, da nogle opdateringer til en ressource kun kan udføres startende fra et bestemt basispunkt.
Fejlhåndtering
En PATCH-anmodning kan mislykkes, hvis nogen af følgende fejl opstår:
Misformet patch-dokument
Serveren returnerer et svar på 400 (dårlig anmodning), hvis PATCH-dokumentet ikke er formateret efter behov.
Ikke-understøttet patch-dokument
Serveren returnerer et 415- svar (ikke-understøttet medietype ) med et Accept-Patch-svarhoved, der indeholder understøttede medietyper, når klienten sender et ikke-understøttet patch-dokument. Dette informerer klienten om, at det PATCH-dokument, der sendes af klienten, ikke kan anvendes på den ønskede ressource.
Ubehandlet anmodning
Serveren returnerer et 422-svar (Unprocessable Entity), når serveren forstår PATCH-dokumentet, men ikke er i stand til at ændre den anmodede ressource, enten fordi det får ressourcen til at blive ugyldig, eller det resulterer i en anden fejltilstand.
Ressource ikke fundet
Serveren returnerer et 404-svar (ikke fundet), når PATCH-dokumentet ikke kan anvendes på en ikke-eksisterende ressource.
Modstridende tilstand
Serveren returnerer et 409 (Conflict) -svar, når serveren ikke kan anvende en patch til den aktuelle tilstand for ressourcen.
Modstridende ændringer
Serveren returnerer et 412-svar (forudsætning mislykkedes), når den forudsætning, der leveres af klienten ved hjælp af If-Match eller If-Unmodified-Since-overskriften, mislykkes. Hvis der ikke er nogen forudsætning, og der er en modstridende ændring, returnerer serveren et 409-svar (Konflikt).
Samtidig ændring
Serveren returnerer et 409-svar (Konflikt), hvis PATCH-anmodningerne til en bestemt ressource skal anvendes i en bestemt rækkefølge, og serveren ikke er i stand til at håndtere samtidige PATCH-anmodninger.
Sikkerhedshensyn
PATCH-anmodningen skal bruge mekanismer såsom betingede anmodninger ved hjælp af Etags og If-Match- anmodningsoverskriften for at sikre, at data ikke er beskadiget under patch. I tilfælde af en fejl i en PATCH-anmodning eller en fiasko i kanalen eller en timeout, kan klienten bruge en GET- anmodning til at kontrollere ressourcens tilstand. Serveren skal sikre, at ondsindede klienter ikke bruger PATCH-metoden til at forbruge for store serverressourcer.