HTTP-methoden

Een HTTP-methode (ook HTTP-verb genoemd) communiceert de intentie van een request: wat wil de client dat er gebeurt met een resource.

De vijf kernmethoden

Methode	CRUD	Actie	Body?
GET	Read	Haal een resource op	Nee
POST	Create	Maak een nieuwe resource aan	Ja
PUT	Update (volledig)	Vervang een resource volledig	Ja
PATCH	Update (gedeeltelijk)	Pas een deel van een resource aan	Ja
DELETE	Delete	Verwijder een resource	Zelden

GET

GET is de meest gebruikte methode. De browser stuurt automatisch een GET als je een URL intypt.

GET http://www.example.com/producten/42

GET haalt enkel data op, de server past niets aan. Resultaten mogen gecachet worden.

POST

POST stuurt data naar de server om een nieuwe resource aan te maken (bv. een nieuw gebruikersaccount, een nieuw bericht). De gegevens zitten in de body van het request.

POST http://www.example.com/api/gebruikers

Body:

{"naam": "Robin", "email": "robin@example.com"}

De server maakt de resource aan en bevestigt dat in zijn antwoord. Hoe dat antwoord er precies uitziet, zie je in Statuscodes.

PUT

PUT vervangt een bestaande resource volledig door de meegestuurde body. Als de resource nog niet bestaat, kan de server hem aanmaken.

PUT http://www.example.com/api/gebruikers/42

Body:

{"naam": "Robin", "email": "robin@nieuwadres.com", "rol": "admin"}

PATCH

PATCH past een deel van een resource aan: je stuurt enkel de velden die moeten veranderen, niet de volledige resource.

PATCH http://www.example.com/api/gebruikers/42

Body:

{"email": "robin@nieuwadres.com"}

DELETE

DELETE verwijdert de aangeduide resource. De server geeft aan dat de resource weg is. Een body is zelden nodig.

DELETE http://www.example.com/api/gebruikers/42

HEAD

HEAD werkt als GET, maar de server stuurt alleen de kop-informatie terug, geen body. Handig om te controleren of een resource bestaat zonder de volledige inhoud te downloaden. Wat die kop-informatie precies bevat, zie je in HTTP-headers.

HEAD http://www.example.com/groot-bestand.iso

Safe en idempotent

Twee begrippen die je vaak tegenkomt bij methoden:

Eigenschap	Betekenis	Methoden
Safe	De methode past de servertoestand niet aan	GET, HEAD
Idempotent	Meerdere identieke requests geven hetzelfde resultaat als één	GET, HEAD, PUT, DELETE

• GET en HEAD zijn safe: ze lezen enkel, schrijven nooit.
• PUT en DELETE zijn idempotent: twee keer dezelfde PUT levert dezelfde toestand op; twee keer DELETE op dezelfde resource, de eerste keer slaagt, de tweede keer geeft de server aan dat de resource niet bestaat, maar de eindtoestand is gelijk (resource is weg).
• POST is niet idempotent: twee keer dezelfde POST maakt twee afzonderlijke resources aan.

Kiezen van de juiste methode

Vraag jezelf af: lees ik iets (GET), maak ik iets nieuws (POST), vervang ik iets volledig (PUT), pas ik iets deels aan (PATCH), of verwijder ik iets (DELETE)? De methode hoort bij de bedoeling van het request, niet enkel bij de URL.

curl en methoden

curl stuurt standaard een GET. Om een andere methode te gebruiken, gebruik je de flag -X:

curl -X GET https://api.example.com/resource/1
curl -X DELETE https://api.example.com/resource/1

Onthoud

• GET leest, POST maakt aan, PUT vervangt volledig, PATCH past gedeeltelijk aan, DELETE verwijdert.
• Safe methoden passen de server niet aan; idempotent methoden geven altijd hetzelfde eindresultaat.
• De methode staat op de eerste regel (startlijn) van een request: METHODE /pad HTTP/1.1.