I RESTful API-design er PUT og PATCH to HTTP-metoder, der bruges til at opdatere ressourcer på serveren, men forskellen mellem PUT vs PATCH i REST API'er er, hvordan de udfører opdateringerne og de scenarier, hvor hver er mest passende. Begge metoder er designet til at modificere eksisterende data, men at forstå forskellen mellem PUT og PATCH i REST API kan hjælpe udviklere med at træffe det bedste valg baseret på arten af den opdatering, de skal udføre. I dette blogindlæg vil vi udforske PUT og PATCH forskellen i REST API, med fokus på PATCH vs update REST debatten, hvornår man skal bruge hver, og give vejledning i at vælge den rigtige metode til forskellige brugssager.
Hvad er PUT i REST API'er?
For at forstå forskellen mellem PUT vs PATCH i REST API'er, skal vi først vide, hvad PUT er i første omgang. Baseret på Afsnit 9.6 RFC 2616, anmoder PUT-metoden i REST API om, at den vedlagte enhed gemmes under den leverede Request-URI.
Hvis Request-URI'en refererer til en allerede eksisterende ressource, SKAL den vedlagte enhed betragtes som en modificeret version af den, der findes på oprindelsesserveren. Hvis Request-URI'en ikke peger på en eksisterende ressource, og denne URI er i stand til at blive defineret som en ny ressource af den anmodende brugeragent, kan oprindelsesserveren oprette ressourcen med denne URI.
Med andre ord bruges PUT-metoden til at opdatere en hel ressource på serveren. Dette gør PUT til en mere "komplet" opdatering, der ofte bruges, når en fuld udskiftning af ressourcen er nødvendig.
Så PUT er bedst til følgende anvendelsestilfælde:
- Opdatering af en komplet ressource (f.eks. opdatering af en brugerprofil med alle nye oplysninger).
- Udskiftning af en hel vare eller post.
- Når ressourcens identitet er klar, og dens data skal opdateres fuldt ud.
I systemer som Elasticsearch, er idempotente operationer nødvendige for at sikre datakonsistens. For eksempel sikrer opdatering af et dokument i Elasticsearch ved hjælp af PUT, at den samme anmodning kan gentages uden utilsigtede bivirkninger.
Hvad er PATCH i REST API'er?
Nu hvor vi har dækket PUT i REST API'er, lad os tage et kig på, hvad PATCH er i REST API'er, og hvordan det virker, før vi sammenligner PUT vs PATCH i REST API'er. Som defineret i RFC 5789, PATCH-metoden i REST API anmoder om, at et sæt ændringer, der er beskrevet i anmodningsenheden, anvendes på den ressource, der er identificeret af Request-URI.
Dette stemmer overens med PUT vs PATCH REST API skelnen, hvor du kun sender de data, der skal ændres, og serveren anvender disse ændringer på den eksisterende ressource uden at ændre hele ressourcen. Udviklere laver ofte patches til at repræsentere disse trinvise ændringer, hvilket sikrer minimal dataoverførsel og effektive opdateringer.
Derfor er PATCH-metoden i REST API bedre egnet til følgende brugssager:
- Opdatering af kun et undersæt af felter i en ressource (f.eks. ændring af en brugers e-mailadresse eller telefonnummer). Et PATCH API-eksempel kunne involvere kun at sende den nye e-mail og lade andre felter være uberørte.
- Forbedring af ydeevnen ved at minimere datanyttelasten.
- Når du vil opdatere en ressource trinvist i stedet for at erstatte den fuldstændigt.
- Opret patches for at indkapsle specifikke feltændringer, som at ændre en brugers e-mail, uden at påvirke urelaterede data.
Til platforme som hovedløst CMS der ofte håndterer komplekse indholdsstrukturer, ved at bruge PATCH til mindre opdateringer – som at ændre et enkelt felt – kan reducere serverbelastningen og forbedre ydeevnen.
Med disse to metoder dækket, bør du have en anstændig idé om, hvad PUT og PATCH er i REST API'er. Men før vi kommer ind på forskellen mellem PUT vs PATCH i REST API'er, skal vi tale om Idempotens i disse to metoder.
Idempotens i PUT Vs Patch i REST API'er
I REST API'er refererer idempotens til egenskaben ved en operation, der, når den gentages flere gange med de samme input, resulterer i det samme resultat. Det betyder, at det at lave den samme anmodning flere gange bør have samme effekt på serveren, uanset hvor mange gange den udføres. Dette er vigtigt for at sikre stabilitet og forudsigelighed i en API. Men hvordan er det relevant for PUT og PATCH forskellen i REST API?
PUT-metode og idempotens
PUT-metoden i REST API er altid idempotent, fordi den er designet til at erstatte hele ressourcen på en specificeret URI med de data, der er angivet i anmodningen. Med andre ord, hvis du udfører en PUT-anmodning flere gange med de samme ressourcedata, vil resultatet altid være det samme.
Hvorfor er PUT idempotent? Når du laver en PUT-anmodning, fortæller du i det væsentlige serveren: "Dette er den komplette og nøjagtige tilstand, jeg ønsker for denne ressource." Uanset om du udsteder PUT-anmodningen én eller flere gange, vil den resulterende ressource altid være identisk.
Overvej f.eks. scenariet, hvor du opdaterer en brugers e-mailadresse. Hvis du laver den samme PUT-anmodning flere gange, vil resultatet ikke blive ændret, fordi ressourcen erstattes af de samme data hver gang.
Eksempel:
| PUT /users/1{“brugernavn”: “john_doe”,,”email”: “[email protected]”} |
Hvis du sender denne anmodning flere gange, vil resultatet altid være det samme:
| {"brugernavn": "john_doe","email": "[email protected]"} |
Selvom brugerens data allerede er dette, ændrer det ikke noget at sende anmodningen igen. Den erstatter dataene med de samme data, så effekten af anmodningen forbliver den samme uanset hvor mange gange den gentages. Det er det, der gør PUT idempotent.
PATCH-metode og idempotens
PATCH-metoden i REST API er på den anden side generelt også idempotent, men med mere fleksibilitet. Når du opretter patches, skal du sikre dig, at operationerne er idempotente (f.eks. indstilling af en værdi) for at undgå utilsigtede bivirkninger fra gentagne anmodninger. Hvorvidt PATCH er idempotent afhænger af operationen og de data, der ændres.
Hvorfor er PATCH idempotent? For PATCH-anmodninger betyder idempotens, at anvendelse af den samme patch flere gange vil have det samme resultat. Dette er sandt, så længe selve plasteret ikke forårsager yderligere bivirkninger eller ændringer, når det påføres gentagne gange. Hvis du bliver ved med at påføre det samme plaster med de samme data, bør resultatet være uændret efter den første påføring.
For eksempel, hvis du kun opdaterer en brugers e-mail, vil gentagne gange sende den samme PATCH-anmodning ikke ændre resultatet efter første gang, selvom anmodningen er lavet flere gange. Brugerens e-mail forbliver den samme, og ressourcens tilstand ændres ikke.
PATCH API Eksempel:
| PATCH /users/1{"email": "[email protected]"} |
Hvis e-mailen allerede var [email protected], vil anvendelse af denne PATCH igen resultere i ingen ændring, hvilket gør den idempotent.
PATCH kan dog også være ikke-idempotent i nogle tilfælde. For eksempel, hvis en PATCH-operation ændrer en tæller eller føjer elementer til en liste (såsom forøgelse af et tal eller tilføjelse til en matrix), kan gentagne anvendelser af den samme PATCH føre til forskellige resultater. Dette ville krænke idempotensegenskaben.
Eksempel på ikke-idempotent API REST PATCH:
| PATCH /counter/1{“increment”: 1} |
Hvis du anvender denne PATCH gentagne gange, vil tælleren blive ved med at stige, hvilket resulterer i forskellige værdier hver gang. Dette er ikke idempotent, fordi resultatet ændres med hver ansøgning.
Nu hvor du kender det væsentlige, kan vi se på nogle eksempler på scenarier for bedre at forstå forskellen mellem PUT vs PATCH i REST API'er.
Eksempelscenarier: PUT vs PATCH i REST API'er
Teori til side, lad os se på forskellen mellem PUT og PATCH med eksempler, herunder både idempotente og ikke-idempotente operationer.
Scenarie 1: PUT-anmodning – Udskiftning af en hel ressource
Forestil dig et API-slutpunkt til styring af produkter i et e-handelssystem. Du skal opdatere alle detaljer om et produkt, herunder dets navn, pris og beskrivelse. Dette er et typisk eksempel på HTTP-metoden PUT vs PATCH, hvor PUT bruges til at erstatte hele produktressourcen.
Oprindeligt produkt:
| GET /products/1001{“id”: 1001,”name”: “Laptop”,,”price”: 999,99,”description”: “En kraftfuld bærbar.”} |
Du vil opdatere produktets pris og beskrivelse. Du sender en PUT-anmodning med hele ressourcen:
PUT-anmodning:
| PUT /products/1001{“id”: 1001,”name”: “Laptop”,,”price”: 899,99,”description”: “En kraftig bærbar computer til nedsat pris.”} |
Hvis du laver denne PUT-anmodning én eller flere gange, vil resultatet altid være det samme. Produktdetaljerne vil blive opdateret for at afspejle den nye pris og beskrivelse, og det samme resultat vil forekomme hver gang. Dette sikrer den idempotente karakter af PUT.
Resultat (efter PUT-anmodning):
| {“id”: 1001,”name”: “Laptop”,,”price”: 899,99,”description”: “En kraftfuld bærbar til nedsat pris.”} |
Scenarie 2: PATCH-anmodning – Opdatering af del af en ressource
Lad os nu overveje en PATCH-anmodning om kun at opdatere en del af produktets detaljer, såsom beskrivelsen. PATCH API eksempel: Hvis du vil ændre produktbeskrivelsen, men ikke prisen, er PATCH det bedre valg. For at implementere dette ville du oprette patches, der kun indeholder de felter, der kræver modifikation, såsom beskrivelsen i dette API REST PATCH eksempel.
Oprindeligt produkt:
| GET /products/1001{“id”: 1001,”name”: “Laptop”,,”price”: 999,99,”description”: “En kraftfuld bærbar.”} |
PATCH-anmodning:
| PATCH /products/1001{"description": "En let, kraftfuld bærbar."} |
Når du sender denne PATCH-anmodning, vil kun beskrivelsesfeltet blive opdateret. Hvis du sender den samme PATCH-anmodning flere gange, forbliver beskrivelsen uændret efter den første opdatering, hvilket gør anmodningen idempotent.
Resultat (efter PATCH-anmodning):
| {“id”: 1001,”name”: “Laptop”,,”price”: 999,99,”description”: “En let, kraftfuld bærbar computer.”} |
Hvis du anvender den samme PATCH igen, vil produktbeskrivelsen stadig være den samme, som den var efter den første PATCH. Resultatet er konsistent, hvilket gør PATCH idempotent i dette scenarie.
Scenarie 3: PATCH-anmodning – Ikke-idempotent operation
Lad os se på en ikke-idempotent PATCH-operation. Antag, at der er et slutpunkt for en brugers tegnebogssaldo, og du vil øge saldoen. Et eksempel på forskel mellem PUT og PATCH kan illustreres her: PATCH tilføjer en værdi til balancen hver gang
Indledende tegnebog:
| GET /users/1/wallet{“id”: 1,”balance”: 100,00} |
PATCH-anmodning:
| PATCH /users/1/wallet{“increment”: 50,00} |
Denne PATCH-anmodning vil øge wallet-saldoen med $50. Hvis du sender denne PATCH-anmodning flere gange, vil saldoen blive ved med at stige med hver PATCH, hvilket fører til et andet resultat hver gang. Dette er ikke-idempotent, fordi anvendelse af den samme PATCH gentagne gange vil forårsage et andet resultat.
Resultat (efter første PATCH-anmodning):
| {"id": 1,"balance": 150,00} |
Resultat (efter anden PATCH-anmodning):
| {"id": 1,"balance": 200,00} |
Her er PATCH ikke idempotent, fordi gentagne anmodninger med de samme data giver forskellige resultater.
Recap: Nøgleforskelle mellem PUT og PATCH i REST API'er
Den vigtigste forskel mellem PUT vs PATCH i REST API er, hvordan de håndterer opdateringer. PUT erstatter hele ressourcen, så eventuelle manglende felter slettes, hvilket kan føre til tab af data. Dette er grunden til, at udviklere opretter patches til delvise opdateringer - for at undgå at overskrive uændrede felter og bevare dataintegriteten.
Dette gør PATCH mere effektiv til delvise opdateringer. Et PATCH API-eksempel er, at hvis du kun vil opdatere en brugers e-mail, vil oprettelse af patches kun sende e-mail-feltet, i modsætning til en PUT-anmodning, der ville kræve alle brugerdata.
Med PUT kræves den fulde datanyttelast. Det betyder, at hvert felt skal sendes, og eventuelle manglende felter vil blive slettet. PATCH sender dog kun de felter, der skal opdateres, hvilket gør det mere effektivt, især for store ressourcer med minimale ændringer. PATCH-metoden i REST API giver mulighed for mere fokuserede og mindre anmodninger, hvilket reducerer dataoverførsel.
Både PUT og PATCH er idempotente. Det betyder, at gentagelse af den samme anmodning vil resultere i det samme resultat. PUT er dog mere forudsigelig, da den erstatter hele ressourcen. PATCH, når det bruges til kun at ændre specificerede felter, kan føre til forskellige resultater afhængigt af hvordan opdateringer håndteres af serveren.
For eksempel, hvis en PATCH øger en tæller, kan gentagne anmodninger føre til forskellige resultater. Ikke desto mindre kan PATCH API-operationer også designes til at være idempotente.
Afslutningsvis bunder PUT- og PATCH-forskellen i REST API ned til arten af opdateringerne: PATCH er til delvise ændringer, mens PUT er til fuldstændig ressourceudskiftning. Begge er idempotente, men PATCH kan være mere kompleks.
Afsluttende tanker
Både PUT og PATCH er grundlæggende HTTP-metoder i REST API-design, men de tjener forskellige formål, hvilket er essensen af PUT- og PATCH-forskellen i REST API. Du kan forbedre effektiviteten, klarheden og funktionaliteten af din API markant ved at forstå forskellen mellem PUT og PATCH med de eksempler, vi dækkede tidligere i denne artikel. Ved at vælge den korrekte metode (PATCH vs. opdatering af REST) baseret på din brugssituation kan du gøre din API mere effektiv, vedligeholdelig og brugervenlig. Overvej altid arten af opdateringen – uanset om den er hel eller delvis – sammen med indvirkningen på ydeevne og dataintegritet, og vælg den metode, der passer bedst til dine behov.
