In RESTful API-ontwerp zijn PUT en PATCH twee HTTP-methoden die worden gebruikt om bronnen op de server bij te werken, maar het verschil tussen PUT en PATCH in REST API's zit in de manier waarop ze de updates uitvoeren en de scenario's waarin elk het meest geschikt is. Beide methoden zijn ontworpen om bestaande gegevens te wijzigen, maar het begrijpen van het PUT- en PATCH-verschil in de REST API kan ontwikkelaars helpen de beste keuze te maken op basis van de aard van de update die ze moeten uitvoeren. In deze blogpost onderzoeken we het verschil tussen PUT en PATCH in de REST API, met de nadruk op het debat over PATCH versus update REST, wanneer we deze moeten gebruiken, en geven we advies over het kiezen van de juiste methode voor verschillende gebruiksscenario's.
Wat is PUT in REST API's?
Om het verschil tussen PUT en PATCH in REST API's te begrijpen, moeten we eerst weten wat PUT in de eerste plaats is. Gebaseerd op Sectie 9.6 RFC 2616, vraagt de PUT-methode in REST API dat de ingesloten entiteit wordt opgeslagen onder de opgegeven Request-URI.
Als de Request-URI verwijst naar een reeds bestaande bron, MOET de ingesloten entiteit worden beschouwd als een aangepaste versie van de entiteit die zich op de oorspronkelijke server bevindt. Als de Request-URI niet naar een bestaande bron verwijst en die URI door de verzoekende user-agent als een nieuwe bron kan worden gedefinieerd, kan de oorspronkelijke server de bron met die URI maken.
Met andere woorden: de PUT-methode wordt gebruikt om een volledige bron op de server bij te werken. Dit maakt PUT een meer “volledige” update, die vaak wordt gebruikt wanneer een volledige vervanging van de bron noodzakelijk is.
PUT is dus het beste voor de volgende gebruikssituaties:
- Het bijwerken van een volledige bron (bijvoorbeeld het bijwerken van een gebruikersprofiel met alle nieuwe informatie).
- Een volledig item of record vervangen.
- Wanneer de identiteit van de bron duidelijk is en de gegevens volledig moeten worden vernieuwd.
In systemen als Elastischzoeken, zijn idempotente bewerkingen nodig om de consistentie van gegevens te garanderen. Het bijwerken van een document in Elasticsearch met PUT zorgt er bijvoorbeeld voor dat hetzelfde verzoek kan worden herhaald zonder onbedoelde bijwerkingen.
Wat is PATCH in REST API's?
Nu we PUT in REST API’s hebben besproken, gaan we eens kijken naar wat PATCH is in REST API’s en hoe het werkt voordat we PUT versus PATCH in REST API’s vergelijken. Zoals gedefinieerd in RFC-5789, vraagt de PATCH-methode in REST API dat een reeks wijzigingen die in de verzoekentiteit worden beschreven, wordt toegepast op de bron die wordt geïdentificeerd door de Request-URI.
Dit komt overeen met het onderscheid PUT versus PATCH REST API, waarbij u alleen de gegevens verzendt die moeten worden gewijzigd, en de server deze wijzigingen op de bestaande bron toepast zonder de hele bron te wijzigen. Ontwikkelaars maken vaak patches om deze stapsgewijze wijzigingen weer te geven, waardoor minimale gegevensoverdracht en efficiënte updates worden gegarandeerd.
Daarom is de PATCH-methode in REST API beter geschikt voor de volgende gebruiksscenario’s:
- Slechts een subset van velden in een bron bijwerken (bijvoorbeeld het e-mailadres of telefoonnummer van een gebruiker wijzigen). Een PATCH API-voorbeeld zou kunnen inhouden dat alleen de nieuwe e-mail wordt verzonden, terwijl andere velden onaangeroerd blijven.
- Verbetering van de prestaties door de datalading te minimaliseren.
- Wanneer u een bron stapsgewijs wilt bijwerken in plaats van deze volledig te vervangen.
- Maak patches om specifieke wijzigingen in het veld vast te leggen, zoals het wijzigen van de e-mail van een gebruiker, zonder dat dit gevolgen heeft voor niet-gerelateerde gegevens.
Voor platforms zoals hoofdloos CMS die vaak omgaan met complexe inhoudsstructuren, kan het gebruik van PATCH voor kleinere updates (zoals het wijzigen van een enkel veld) de serverbelasting verminderen en de prestaties verbeteren.
Nu deze twee methoden aan bod komen, zou je een goed idee moeten hebben van wat PUT en PATCH zijn in REST API's. Voordat we echter ingaan op het verschil tussen PUT en PATCH in REST API's, moeten we het hebben over Idempotence in deze twee methoden.
Idempotence in PUT versus patch in REST API's
In REST API's verwijst idempotence naar de eigenschap van een bewerking die, wanneer deze meerdere keren wordt herhaald met dezelfde invoer, tot hetzelfde resultaat leidt. Dit betekent dat het meerdere keren uitvoeren van hetzelfde verzoek hetzelfde effect op de server moet hebben, ongeacht hoe vaak het wordt uitgevoerd. Dit is belangrijk voor het garanderen van stabiliteit en voorspelbaarheid in een API. Maar hoe is dit relevant voor het PUT- en PATCH-verschil in de REST API?
PUT-methode en Idempotence
De PUT-methode in REST API is altijd idempotent omdat deze is ontworpen om de volledige bron op een opgegeven URI te vervangen door de gegevens die in het verzoek zijn verstrekt. Met andere woorden: als u meerdere keren een PUT-verzoek uitvoert met dezelfde brongegevens, zal de uitkomst altijd hetzelfde zijn.
Waarom is PUT Idempotent? Wanneer u een PUT-verzoek doet, zegt u in feite tegen de server: “Dit is de volledige en exacte staat die ik voor deze bron wil.” Of u het PUT-verzoek nu één keer of meerdere keren indient, de resulterende bron zal altijd identiek zijn.
Neem bijvoorbeeld het scenario waarin u het e-mailadres van een gebruiker bijwerkt. Als u meerdere keren hetzelfde PUT-verzoek doet, verandert het resultaat niet, omdat de bron elke keer wordt vervangen door dezelfde gegevens.
Voorbeeld:
| PUT /users/1{“gebruikersnaam”: “john_doe”,”email”: “[email protected]”} |
Als u dit verzoek meerdere keren verzendt, is het resultaat altijd hetzelfde:
| {“gebruikersnaam”: “john_doe”,”email”: “[email protected]”} |
Zelfs als de gegevens van de gebruiker dit al zijn, verandert het opnieuw verzenden van het verzoek niets. Het vervangt de gegevens door dezelfde gegevens, zodat het effect van het verzoek hetzelfde blijft, ongeacht hoe vaak het wordt herhaald. Dit is wat PUT idempotent maakt.
PATCH-methode en Idempotence
De PATCH-methode in REST API is daarentegen over het algemeen ook idempotent, maar met meer flexibiliteit. Wanneer u patches maakt, zorg er dan voor dat de bewerkingen idempotent zijn (bijvoorbeeld het instellen van een waarde) om onbedoelde bijwerkingen van herhaalde verzoeken te voorkomen. Of PATCH idempotent is, hangt af van de bewerking en de gegevens die worden gewijzigd.
Waarom is PATCH Idempotent? Voor PATCH-verzoeken betekent idempotence dat het meerdere keren toepassen van dezelfde patch hetzelfde resultaat zal opleveren. Dit geldt zolang de pleister zelf geen extra bijwerkingen of veranderingen veroorzaakt wanneer hij herhaaldelijk wordt aangebracht. Als u dezelfde pleister met dezelfde gegevens blijft aanbrengen, zou het resultaat na de eerste toepassing onveranderd moeten zijn.
Als u bijvoorbeeld alleen de e-mail van een gebruiker bijwerkt, zal het herhaaldelijk verzenden van hetzelfde PATCH-verzoek het resultaat na de eerste keer niet veranderen, zelfs niet als het verzoek meerdere keren wordt gedaan. Het e-mailadres van de gebruiker blijft hetzelfde en de status van de bron verandert niet.
PATCH API-voorbeeld:
| PATCH /users/1{“email”: “[email protected]”} |
Als de e-mail al [email protected] was, zal het opnieuw toepassen van deze PATCH geen verandering tot gevolg hebben, waardoor deze idempotent wordt.
PATCH kan in sommige gevallen echter ook niet-idempotent zijn. Als een PATCH-bewerking bijvoorbeeld een teller wijzigt of items aan een lijst toevoegt (zoals het verhogen van een getal of het toevoegen aan een array), kunnen herhaalde toepassingen van dezelfde PATCH tot verschillende resultaten leiden. Dit zou in strijd zijn met de eigenschap idempotence.
Niet-idempotente API REST PATCH Voorbeeld:
| PATCH /counter/1{“increment”: 1} |
Als u deze PATCH herhaaldelijk toepast, blijft de teller stijgen, wat elke keer in andere waarden resulteert. Dit is niet idempotent omdat de uitkomst bij elke aanvraag verandert.
Nu u de essentie kent, kunnen we enkele voorbeeldscenario's bekijken om het verschil tussen PUT en PATCH in REST API's beter te begrijpen.
Voorbeeldscenario's: PUT versus PATCH in REST API's
Laten we, afgezien van de theorie, eens kijken naar het verschil tussen PUT en PATCH met voorbeelden, inclusief zowel idempotente als niet-idempotente bewerkingen.
Scenario 1: PUT-verzoek – Vervanging van een volledige resource
Stel je een API-eindpunt voor voor het beheren van producten in een e-commercesysteem. U moet alle details van een product bijwerken, inclusief de naam, prijs en beschrijving. Dit is een typisch voorbeeld van de HTTP-methode PUT vs PATCH, waarbij PUT wordt gebruikt om de volledige productbron te vervangen.
Oorspronkelijk product:
| KRIJG /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Een krachtige laptop.”} |
U wilt de prijs en beschrijving van het product bijwerken. U verzendt een PUT-verzoek met de volledige resource:
PUT-verzoek:
| PUT /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 899,99,”description”: “Een krachtige laptop met korting.”} |
Als u dit PUT-verzoek één of meerdere keren doet, is het resultaat altijd hetzelfde. De productgegevens worden bijgewerkt om de nieuwe prijs en beschrijving weer te geven, en elke keer zal hetzelfde resultaat optreden. Dit waarborgt het idempotente karakter van PUT.
Resultaat (na PUT-verzoek):
| {“id”: 1001,”name”: “Laptop”,”price”: 899,99,”description”: “Een krachtige laptop met korting.”} |
Scenario 2: PATCH-verzoek – Een deel van een bron bijwerken
Laten we nu eens een PATCH-verzoek overwegen om slechts een deel van de productdetails bij te werken, zoals de beschrijving. PATCH API-voorbeeld: Als u de productbeschrijving wilt wijzigen, maar niet de prijs, is PATCH de betere keuze. Om dit te implementeren, zou u patches maken die alleen de velden bevatten die moeten worden gewijzigd, zoals de beschrijving in dit API REST PATCH-voorbeeld.
Oorspronkelijk product:
| KRIJG /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Een krachtige laptop.”} |
PATCH-verzoek:
| PATCH /products/1001{“description”: “Een lichtgewicht, krachtige laptop.”} |
Wanneer u dit PATCH-verzoek verzendt, wordt alleen het beschrijvingsveld bijgewerkt. Als u hetzelfde PATCH-verzoek meerdere keren verzendt, blijft de beschrijving na de eerste update ongewijzigd, waardoor het verzoek idempotent wordt.
Resultaat (na PATCH-verzoek):
| {“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Een lichtgewicht, krachtige laptop.”} |
Als u dezelfde PATCH opnieuw aanbrengt, zal de productbeschrijving nog steeds dezelfde zijn als na de eerste PATCH. Het resultaat is consistent, wat PATCH in dit scenario idempotent maakt.
Scenario 3: PATCH-verzoek – niet-idempotente bewerking
Laten we eens kijken naar een niet-idempotente PATCH-bewerking. Stel dat er een eindpunt is voor het portemonneesaldo van een gebruiker en u wilt het saldo verhogen. Een voorbeeld van het verschil tussen PUT en PATCH kan hier worden geïllustreerd: PATCH voegt elke keer een waarde toe aan het saldo
Initiële portemonnee:
| GET /users/1/wallet{“id”: 1,”saldo”: 100,00} |
PATCH-verzoek:
| PATCH /users/1/wallet{“verhoging”: 50,00} |
Dit PATCH-verzoek verhoogt het portemonneesaldo met €50. Als u dit PATCH-verzoek meerdere keren verzendt, zal het saldo bij elke PATCH blijven stijgen, wat elke keer tot een ander resultaat leidt. Dit is niet-idempotent omdat het herhaaldelijk toepassen van dezelfde PATCH een ander resultaat zal veroorzaken.
Resultaat (na eerste PATCH-verzoek):
| {“id”: 1,”saldo”: 150,00} |
Resultaat (na tweede PATCH-verzoek):
| {“id”: 1,”saldo”: 200,00} |
Hier is PATCH niet idempotent omdat herhaalde verzoeken met dezelfde gegevens verschillende resultaten opleveren.
Samenvatting: belangrijkste verschillen tussen PUT versus PATCH in REST API's
Het belangrijkste verschil tussen PUT en PATCH in REST API is de manier waarop ze omgaan met updates. PUT vervangt de volledige bron, zodat ontbrekende velden worden weggevaagd, wat tot gegevensverlies kan leiden. Dit is de reden waarom ontwikkelaars patches maken voor gedeeltelijke updates, om te voorkomen dat ongewijzigde velden worden overschreven en de gegevensintegriteit behouden blijft.
Dit maakt PATCH efficiënter voor gedeeltelijke updates. Een voorbeeld van de PATCH API is dat als u alleen de e-mail van een gebruiker wilt bijwerken, het maken van patches alleen het e-mailveld verzendt, in tegenstelling tot een PUT-verzoek waarvoor de volledige gebruikersgegevens nodig zijn.
Met PUT is de volledige datalading vereist. Dit betekent dat elk veld moet worden verzonden en dat ontbrekende velden worden gewist. PATCH verzendt echter alleen de velden die moeten worden bijgewerkt, waardoor het efficiënter wordt, vooral voor grote bronnen met minimale wijzigingen. De PATCH-methode in REST API maakt meer gerichte en kleinere verzoeken mogelijk, waardoor de gegevensoverdracht wordt verminderd.
Zowel PUT als PATCH zijn idempotent. Dit betekent dat het herhalen van hetzelfde verzoek tot hetzelfde resultaat zal leiden. PUT is echter voorspelbaarder omdat het de volledige bron vervangt. Wanneer PATCH wordt gebruikt om alleen gespecificeerde velden te wijzigen, kan dit tot verschillende resultaten leiden, afhankelijk van hoe updates door de server worden afgehandeld.
Als een PATCH bijvoorbeeld een teller verhoogt, kunnen herhaalde verzoeken tot verschillende uitkomsten leiden. Niettemin kunnen PATCH API-bewerkingen ook zo worden ontworpen dat ze idempotent zijn.
Concluderend komt het verschil tussen PUT en PATCH in de REST API neer op de aard van de updates: PATCH is voor gedeeltelijke wijzigingen, terwijl PUT voor volledige vervanging van bronnen is. Beide zijn idempotent, maar PATCH kan complexer zijn.
Laatste gedachten
Zowel PUT als PATCH zijn fundamentele HTTP-methoden in REST API-ontwerp, maar ze dienen verschillende doeleinden, wat de essentie is van het PUT- en PATCH-verschil in REST API. U kunt de efficiëntie, duidelijkheid en functionaliteit van uw API aanzienlijk verbeteren door het verschil tussen PUT en PATCH te begrijpen aan de hand van de voorbeelden die we eerder in dit artikel hebben besproken. Door de juiste methode (PATCH versus update REST) te kiezen op basis van uw gebruiksscenario, kunt u uw API efficiënter, onderhoudbaarder en gebruiksvriendelijker maken. Houd altijd rekening met de aard van de update (of deze nu volledig of gedeeltelijk is), samen met de impact op de prestaties en gegevensintegriteit, en selecteer de methode die het beste aansluit bij uw behoeften.
