Hoe test je een PATCH-verzoek in je REST API: stappenplan met cURL en Postman

Je past via je eigen API het e-mailadres van één klant aan, en na het opslaan blijkt het telefoonnummer leeg te zijn. De oorzaak is bijna altijd dezelfde: het verzoek stuurde het hele object mee in plaats van alleen het gewijzigde veld. Met een PATCH-verzoek en twee controleverzoeken zie je dat aankomen voordat een klant het merkt.

Key takeaways

• PATCH stuurt alleen de velden mee die moeten veranderen. PUT vervangt het volledige object, inclusief de velden die je niet meestuurde.
• Test elke PATCH met drie verzoeken: een GET vooraf, de PATCH zelf, en een GET achteraf. Zonder die twee GET-verzoeken weet je niet wat er stil is veranderd.
• Een statuscode is geen bewijs. Een endpoint kan 200 teruggeven en tóch het verkeerde veld hebben overschreven.
• Je hebt geen betaald gereedschap nodig. cURL staat waarschijnlijk al op je machine.
• Test op een ontwikkel- of testomgeving. Een mislukte PATCH op productiedata repareer je niet met een tweede PATCH.

Wat PATCH anders doet dan PUT

PATCH is de HTTP-methode voor een gedeeltelijke wijziging. De methode is vastgelegd in RFC 5789. Je stuurt uitsluitend de velden mee die moeten veranderen, en de server laat de rest van het record staan.

PUT werkt anders. Daar stuur je de volledige representatie van het object, en wat je weglaat hoort te verdwijnen. Een frontend die PUT gebruikt terwijl de bouwer PATCH-gedrag verwacht, wist velden zonder ook maar één foutmelding. Dat soort fout valt pas weken later op, meestal in de gegevens van een echte klant.

Daarom test je een PATCH niet op de statuscode alleen. Je test op wat er in het record staat voor en na het verzoek.

Stappenplan: een PATCH testen met cURL

cURL verstuurt HTTP-verzoeken vanaf de opdrachtregel. Controleer eerst of je het al hebt met curl --version. Krijg je een versienummer terug, dan kun je meteen door. cURL zit standaard op macOS, op de meeste Linux-distributies en op recente Windows-versies.

Stap 1: leg de beginsituatie vast

curl -s https://api.jouwdomein.be/api/gebruikers/42

Resultaat: je ziet het volledige record op je scherm. Kopieer dat antwoord naar een tekstbestand. Dit is je nulmeting. Zonder nulmeting kun je straks niets vergelijken en test je eigenlijk niets.

Stap 2: stel het PATCH-verzoek samen

Een PATCH heeft drie onderdelen: de methode, de header Content-Type en een body met alleen de velden die veranderen.

curl -i -X PATCH https://api.jouwdomein.be/api/gebruikers/42 \
  -H "Content-Type: application/json" \
  -d '{"email":"nieuw@voorbeeld.be"}'

Resultaat: je ziet dankzij -i de statusregel en de headers bovenaan het antwoord staan. Zie je die niet, dan bereikte het verzoek je server niet en is er iets mis met de URL of het netwerk.

Stap 3: voeg authenticatie toe

Is je API beveiligd met een token, dan gaat dat mee als extra header.

curl -i -X PATCH https://api.jouwdomein.be/api/gebruikers/42 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jouw-token" \
  -d '{"email":"nieuw@voorbeeld.be"}'

Resultaat: de statuscode verandert van 401 naar 200 of 204. Blijft er 401 staan, dan is het token verlopen of leest je server de header niet uit.

Stap 4: controleer het antwoord

Lees de statusregel. 200 betekent gelukt met een antwoord in de body, 204 betekent gelukt zonder body. Alles vanaf 400 is een weigering.

Resultaat: je weet nu of de server het verzoek accepteerde. Je weet nog niet of hij het juiste deed. Dat komt in de volgende stap.

Stap 5: haal het record opnieuw op en vergelijk

curl -s https://api.jouwdomein.be/api/gebruikers/42

Resultaat: leg dit antwoord naast je nulmeting uit stap 1. Alleen het e-mailadres hoort te verschillen. Is er nog een veld veranderd of leeggelopen, dan behandelt je endpoint de PATCH intern als een PUT. Dat is de bug die je zocht.

Stap 6: test wat er fout hoort te gaan

Stuur bewust drie foute verzoeken: een onbekend ID, een veld dat niet bestaat en een lege body.

curl -i -X PATCH https://api.jouwdomein.be/api/gebruikers/999999 \
  -H "Content-Type: application/json" \
  -d '{"email":"nieuw@voorbeeld.be"}'

Resultaat: je krijgt 404 op een onbekend ID, en een duidelijke foutmelding bij een ongeldig veld. Krijg je 200 op een record dat niet bestaat, dan maakt je endpoint stilzwijgend iets aan of negeert het de invoer. Beide zijn ernstiger dan een nette foutmelding.

Stappenplan: dezelfde test in Postman

Postman doet hetzelfde met een venster in plaats van een opdrachtregel. Dat helpt vooral als je de test wilt bewaren en herhalen.

Stap 1: maak het verzoek aan

Kies New, dan HTTP Request. Zet de methode op PATCH en plak de URL van je endpoint erin.

Resultaat: links van het URL-veld staat PATCH. Staat er nog GET, dan test je straks het verkeerde.

Stap 2: zet de headers

Ga naar het tabblad Headers en voeg Content-Type met waarde application/json toe. Werk je met een token, voeg dan ook Authorization toe.

Resultaat: beide regels staan aangevinkt in de lijst. Een uitgevinkte regel wordt niet meegestuurd, en dat is een klassieke oorzaak van een onverklaarbare 415.

Stap 3: vul de body

Tabblad Body, dan raw, en kies JSON in het keuzemenu ernaast.

{ "email": "nieuw@voorbeeld.be" }

Resultaat: Postman kleurt de JSON en meldt het direct als er een komma of aanhalingsteken ontbreekt. Blijft de melding staan, dan is je JSON ongeldig en stuurt de server sowieso een 400 terug.

Stap 4: bewaar het verzoek in een collectie

Klik Save en kies een collectie, bijvoorbeeld met de naam van het project.

Resultaat: het verzoek staat links in de zijbalk en is met één klik opnieuw uit te voeren. Zo herhaal je deze test na elke wijziging aan je API zonder iets over te typen.

Wat de statuscodes je vertellen

Gratis gereedschap dat je vandaag kunt gebruiken

Controleer bij elke tool zelf de actuele voorwaarden voordat je hem in een klantproject opneemt. Voorwaarden veranderen, en een artikel is nooit actueler dan de dag dat het geschreven is.

Tips en tricks

• Bewaar je nulmeting in een bestand en gebruik een diff-tool om de twee antwoorden te vergelijken. Met je ogen zie je een verdwenen veld tussen dertig regels JSON niet.
• Zet -i standaard in je cURL-commando. De headers vertellen je vaak meer dan de body, zeker bij een omleiding of een cachelaag ertussen.
• Test één veld per verzoek. Stuur je er vier tegelijk en het gaat mis, dan weet je niet welk veld de oorzaak is.
• Let op een omleiding. Een server die je van http naar https stuurt, kan onderweg de methode en de body kwijtraken. Gebruik altijd de https-URL.
• Sla je token nooit op in een gedeelde collectie. Zet het in een omgevingsvariabele, zodat het niet meelift naar een collega of een repository.
• Doe dezelfde test met het token van een andere gebruiker. Als die het record van iemand anders kan wijzigen, heb je geen testprobleem maar een lek.

Zelfscan: is jouw PATCH-endpoint klaar voor productie?

Beantwoord elke vraag eerst zelf, klap daarna het antwoord open.

Wat je nu kunt doen

Pak je eigen API en draai de zes cURL-stappen op één record in je testomgeving. Dat kost je zelden meer dan een kwartier. Je weet daarna zeker of je PATCH alleen wijzigt wat je meestuurde, en of een vreemd token wordt tegengehouden.

Loop je vast op de autorisatie of op validatie die per endpoint anders uitpakt, dan kijkt HisarWeb mee. We bouwen API's en backend-integraties voor KMO's in de Benelux, en we leveren de tests erbij zodat je het daarna zelf kunt controleren.