In RESTful API design zijn PUT en PATCH twee HTTP-methoden om resources op de server bij te werken, maar het verschil tussen PUT en PATCH in REST APIs zit in de manier waarop ze die updates uitvoeren en in welke situaties elk het meest geschikt is. Beide methoden zijn bedoeld om bestaande data te wijzigen, maar wie het PUT- en PATCH-verschil in REST API begrijpt, kan als developer de beste keuze maken op basis van de aard van de benodigde update. In dit blogbericht verkennen we het PUT- en PATCH-verschil in REST API, met aandacht voor het PATCH vs update REST debat, wanneer je elk gebruikt en hoe je de juiste methode kiest voor verschillende situaties.
Wat is PUT in REST APIs?
Om het verschil tussen PUT en PATCH in REST APIs te begrijpen, moeten we eerst weten wat PUT precies inhoudt. Op basis van Sectie 9.6 RFC 2616, de PUT-methode in REST API verzoekt de server om de meegestuurde entiteit op te slaan onder de opgegeven Request-URI.
Als de Request-URI verwijst naar een al bestaande resource, moet de meegestuurde entiteit worden beschouwd als een bijgewerkte versie van de resource op de oorspronkelijke server. Als de Request-URI niet verwijst naar een bestaande resource, maar die URI wel als nieuwe resource kan worden gedefinieerd door de aanvragende user agent, dan kan de oorspronkelijke server de resource aanmaken onder die URI.
Kortom: de PUT-methode wordt gebruikt om een volledige resource op de server te vervangen. Dat maakt PUT een meer "complete" update, die je inzet wanneer een resource volledig opnieuw moet worden ingesteld.
PUT is het meest geschikt voor de volgende gevallen:
- Een volledige resource bijwerken (bijvoorbeeld een gebruikersprofiel vervangen met volledig nieuwe gegevens).
- Een heel item of record vervangen.
- Wanneer de identiteit van een resource duidelijk is en de gegevens volledig moeten worden ververst.
I need more context to provide an accurate translation. The phrase "In systems like" appears incomplete. Could you please provide the full sentence or UI label you'd like me to translate? Elasticsearch, zijn idempotente operaties noodzakelijk om dataconsistentie te garanderen. Het bijwerken van een document in Elasticsearch via PUT zorgt er bijvoorbeeld voor dat hetzelfde verzoek herhaald kan worden zonder onbedoelde neveneffecten.
Wat is PATCH in REST APIs?
Nu we PUT in REST APIs hebben behandeld, kijken we naar wat PATCH is in REST APIs en hoe het werkt, voordat we PUT en PATCH in REST APIs vergelijken. Zoals gedefinieerd in RFC 5789, verzoekt de PATCH-methode in REST API de server om een reeks wijzigingen, beschreven in de verzoekentiteit, toe te passen op de resource die wordt geïdentificeerd door de Request-URI.
Dit sluit aan op het verschil tussen PUT en PATCH in REST API: je stuurt alleen de gegevens mee die gewijzigd moeten worden, en de server past die wijzigingen toe op de bestaande resource zonder het geheel te overschrijven. Ontwikkelaars maken vaak patches aan om deze incrementele wijzigingen vast te leggen, wat zorgt voor minimale dataoverdracht en efficiënte updates.
Daarom is de PATCH-methode in REST API beter geschikt voor de volgende gevallen:
- Alleen een deel van de velden in een resource bijwerken (bijvoorbeeld het e-mailadres of telefoonnummer van een gebruiker wijzigen). Een PATCH API-voorbeeld kan inhouden dat je alleen het nieuwe e-mailadres meestuurt en andere velden ongemoeid laat.
- Betere prestaties door de hoeveelheid meegestuurde data te beperken.
- Wanneer je een resource stap voor stap wilt bijwerken in plaats van volledig te vervangen.
- Patches aanmaken voor specifieke veldwijzigingen, zoals het aanpassen van het e-mailadres van een gebruiker, zonder niet-gerelateerde gegevens te beïnvloeden.
Voor platforms zoals CMS zonder frontend die vaak complexe contentstructuren verwerken, kan PATCH voor kleinere updates - zoals het wijzigen van een enkel veld - de serverbelasting verlagen en de prestaties verbeteren.
Nu beide methoden zijn toegelicht, heb je een goed beeld van wat PUT en PATCH zijn in REST APIs. Maar voordat we ingaan op het verschil tussen PUT en PATCH in REST APIs, moeten we het hebben over idempotentie bij deze twee methoden.
Idempotentie bij PUT vs PATCH in REST APIs
In REST APIs verwijst idempotentie naar de eigenschap van een operatie waarbij herhaling met dezelfde invoer altijd hetzelfde resultaat oplevert. Hetzelfde verzoek meerdere keren uitvoeren heeft dus altijd hetzelfde effect op de server, ongeacht hoe vaak het wordt uitgevoerd. Dat is belangrijk voor stabiliteit en voorspelbaarheid in een API. Maar wat heeft dit te maken met het verschil tussen PUT en PATCH in REST API?
PUT-methode en idempotentie
De PUT-methode in REST API is altijd idempotent, omdat hij is ontworpen om de volledige resource op een opgegeven URI te vervangen door de gegevens in het verzoek. Met andere woorden: als je meerdere keren hetzelfde PUT-verzoek uitvoert met dezelfde resourcegegevens, is het resultaat altijd identiek.
Waarom is PUT idempotent? Wanneer je een PUT-verzoek doet, vertel je de server in feite: "Dit is de volledige en exacte toestand die ik voor deze resource wil." Of je het PUT-verzoek nu één keer of tien keer verstuurt, de resulterende resource is altijd hetzelfde.
Stel dat je het e-mailadres van een gebruiker bijwerkt. Als je hetzelfde PUT-verzoek meerdere keren uitvoert, verandert het resultaat niet, omdat de resource elke keer door dezelfde gegevens wordt vervangen.
Voorbeeld:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Als je dit verzoek meerdere keren verstuurt, is het resultaat altijd hetzelfde:
| {"username": "john_doe","email": "[email protected]"} |
Zelfs als de gebruikersdata al deze waarden heeft, verandert het opnieuw versturen van het verzoek niets. De data wordt vervangen door dezelfde data, zodat het effect hetzelfde blijft ongeacht hoe vaak het verzoek wordt herhaald. Dat is wat PUT idempotent maakt.
PATCH-methode en idempotentie
De PATCH-methode in REST API is over het algemeen ook idempotent, maar biedt meer flexibiliteit. Zorg er bij het opstellen van patches voor dat de bewerkingen idempotent zijn (bijvoorbeeld het instellen van een vaste waarde) om onbedoelde neveneffecten bij herhaalde verzoeken te voorkomen. Of PATCH idempotent is, hangt af van de bewerking en de data die wordt aangepast.
Waarom is PATCH idempotent? Bij PATCH-verzoeken betekent idempotentie dat dezelfde patch meerdere keren toepassen altijd hetzelfde resultaat oplevert. Dit geldt zolang de patch zelf geen extra neveneffecten of wijzigingen veroorzaakt bij herhaalde toepassing. Als je dezelfde patch met dezelfde data blijft toepassen, verandert het resultaat na de eerste keer niet meer.
Als je bijvoorbeeld alleen het e-mailadres van een gebruiker bijwerkt, zal het herhaaldelijk versturen van hetzelfde PATCH-verzoek het resultaat na de eerste keer niet veranderen, ook niet als het verzoek meerdere keren wordt gedaan. Het e-mailadres van de gebruiker blijft gelijk en de toestand van de resource verandert niet.
PATCH API voorbeeld:
| PATCH /users/1{"email": "[email protected]"} |
Als het e-mailadres al [email protected] was, leidt het opnieuw toepassen van deze PATCH tot geen enkele wijziging, wat het idempotent maakt.
PATCH kan in sommige gevallen echter ook niet-idempotent zijn. Als een PATCH-bewerking bijvoorbeeld een teller aanpast of items aan een lijst toevoegt (zoals een getal ophogen of iets aan een array toevoegen), kunnen herhaalde toepassingen van dezelfde PATCH tot verschillende resultaten leiden. Dat zou de idempotentie-eigenschap schenden.
Niet-idempotent API REST PATCH-voorbeeld:
| PATCH /counter/1{"increment": 1} |
Als je deze PATCH herhaaldelijk toepast, blijft de teller oplopen en krijg je elke keer een andere waarde. Dit is niet idempotent, omdat het resultaat bij elke toepassing verandert.
Nu je de basis kent, kunnen we een aantal voorbeeldscenario's bekijken om het verschil tussen PUT en PATCH in REST APIs beter te begrijpen.
Voorbeeldscenario's: PUT vs PATCH in REST APIs
Theorie genoeg. Laten we het verschil tussen PUT en PATCH aan de hand van voorbeelden bekijken, inclusief zowel idempotente als niet-idempotente bewerkingen.
Scenario 1: PUT-verzoek - een volledige resource vervangen
Stel je een API-endpoint voor dat producten beheert in een e-commercesysteem. Je wilt alle details van een product bijwerken, inclusief de naam, prijs en beschrijving. Dit is een typisch voorbeeld van de HTTP-methode PUT versus PATCH, waarbij PUT wordt gebruikt om de volledige productresource te vervangen.
Initieel Product
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Je wilt de prijs en beschrijving van het product bijwerken. Je stuurt een PUT-verzoek met de volledige resource:
PUT-verzoek:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Of je dit PUT-verzoek één keer of meerdere keren uitvoert, het resultaat is altijd hetzelfde. De productgegevens worden bijgewerkt met de nieuwe prijs en beschrijving, en dat resultaat is elke keer identiek. Dit garandeert het idempotente karakter van PUT.
Resultaat (na PUT-verzoek):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Scenario 2: PATCH-verzoek - een deel van een resource bijwerken
Laten we nu een PATCH-verzoek bekijken waarbij je alleen een deel van de productgegevens bijwerkt, zoals de beschrijving. PATCH API-voorbeeld: als je de productbeschrijving wilt aanpassen zonder de prijs te wijzigen, is PATCH de betere keuze. Je maakt daarvoor een patch aan die alleen de velden bevat die moeten worden gewijzigd, zoals de beschrijving in dit API REST PATCH-voorbeeld.
Initieel Product
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
PATCH-aanvraag:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Wanneer je dit PATCH-verzoek verstuurt, wordt alleen het beschrijvingsveld bijgewerkt. Als je hetzelfde PATCH-verzoek meerdere keren verstuurt, blijft de beschrijving na de eerste update ongewijzigd, waardoor het verzoek idempotent is.
Resultaat (na PATCH-verzoek):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Als je hetzelfde PATCH-verzoek opnieuw verstuurt, blijft de productbeschrijving gelijk aan die na de eerste PATCH. Het resultaat is consistent, wat PATCH in dit scenario idempotent maakt.
Scenario 3: PATCH-verzoek – Niet-idempotente bewerking
Laten we kijken naar een niet-idempotente PATCH-bewerking. Stel dat er een endpoint is voor het walletbedrag van een gebruiker, en je wilt het saldo verhogen. Een concreet verschil tussen PUT en PATCH is hier goed te illustreren: PATCH voegt elke keer een waarde toe aan het saldo.
Initieel saldo:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
PATCH-aanvraag:
| PATCH /users/1/wallet{"increment": 50.00} |
Dit PATCH-verzoek verhoogt het walletbedrag met $50. Als je dit PATCH-verzoek meerdere keren verstuurt, blijft het saldo bij elke PATCH stijgen, wat elke keer een ander resultaat geeft. Dit is niet-idempotent, omdat het herhaaldelijk toepassen van dezelfde PATCH steeds een ander resultaat oplevert.
Resultaat (na het eerste PATCH-verzoek):
| {"id": 1,"balance": 150.00} |
Resultaat (na het tweede PATCH-verzoek):
| {"id": 1,"balance": 200.00} |
Hier is PATCH niet idempotent, omdat herhaalde verzoeken met dezelfde gegevens telkens een ander resultaat opleveren.
Samenvatting: belangrijkste verschillen tussen PUT en PATCH in REST APIs
Het belangrijkste verschil tussen PUT en PATCH in REST API zit in de manier waarop ze updates verwerken. PUT vervangt de volledige resource, waardoor ontbrekende velden worden gewist. Dit kan tot dataverlies leiden. Daarom gebruiken ontwikkelaars PATCH voor gedeeltelijke updates: zo voorkom je dat ongewijzigde velden worden overschreven en blijft de data-integriteit intact.
Dit maakt PATCH efficiënter voor gedeeltelijke updates. Een voorbeeld van PATCH API: als je alleen het e-mailadres van een gebruiker wilt bijwerken, stuurt PATCH uitsluitend het e-mailveld mee. Een PUT-verzoek zou de volledige gebruikersdata vereisen.
Bij PUT moet de volledige datapayload worden meegestuurd. Dat betekent dat elk veld aanwezig moet zijn; ontbrekende velden worden gewist. PATCH stuurt alleen de velden mee die bijgewerkt moeten worden, wat het efficiënter maakt, zeker bij grote resources met minimale wijzigingen. De PATCH-methode in REST API maakt kleinere, gerichtere verzoeken mogelijk en beperkt zo de dataoverdracht.
Zowel PUT als PATCH zijn idempotent. Dat betekent dat het herhalen van hetzelfde verzoek steeds hetzelfde resultaat oplevert. PUT is daarbij voorspelbaarder, omdat het de volledige resource vervangt. PATCH, gebruikt om alleen bepaalde velden te wijzigen, kan afhankelijk van de serverimplementatie tot wisselende resultaten leiden.
Als een PATCH bijvoorbeeld een teller ophoogt, kunnen herhaalde verzoeken tot verschillende uitkomsten leiden. PATCH API-bewerkingen kunnen echter ook ontworpen worden om idempotent te zijn.
Samengevat komt het verschil tussen PUT en PATCH in REST API neer op de aard van de update: PATCH is voor gedeeltelijke wijzigingen, PUT voor volledige resource-vervanging. Beide zijn idempotent, maar PATCH kan complexer zijn.
Laatste Gedachten
PUT en PATCH zijn beide fundamentele HTTP-methoden in REST API-ontwerp, maar ze dienen verschillende doelen. Dat is precies de kern van het verschil tussen PUT en PATCH in REST API. Door te begrijpen wanneer je welke methode gebruikt, zoals aan de hand van de voorbeelden eerder in dit artikel, kun je de efficiëntie, duidelijkheid en functionaliteit van je API aanzienlijk verbeteren. Kies de juiste methode (PATCH versus update REST) op basis van je use case, zodat je API efficiënter, beter onderhoudbaar en gebruiksvriendelijker wordt. Houd altijd rekening met de aard van de update, of die volledig of gedeeltelijk is, samen met de impact op prestaties en data-integriteit, en kies de methode die het beste aansluit bij je behoeften.
