Veilige en idempotente methoden

In hoofdstuk 1 stuurde je twee soorten verzoeken naar practice-api: GET, dat om een resource vraagt, en HEAD, dat om hetzelfde antwoord zonder body vraagt. Het eerste woord van de verzoekregel is de methode, en die vertelt de server wat de client gedaan wil hebben. In dit hoofdstuk bouw je verzoeken voor elke methode, URL, header en body, en de methode komt eerst, dus hier ook.

HTTP definieert meer methoden dan GET en HEAD. Drie daarvan doen ertoe voor deze cursus: POST, PUT en DELETE. practice-api accepteert alleen GET en HEAD, dus de andere stuur je er niet naartoe; de server die je in hoofdstuk 5 schrijft, accepteert alle vijf.

Elke methode doet twee beloften waarop een client kan vertrouwen. Beide gaan over wat er met de gegevens op de server gebeurt, niet over het antwoord dat terugkomt.

Veilig

Een methode is veilig (safe) als de client om geen enkele wijziging vraagt. Het record van een boek lezen verandert niets op de server, dus GET is veilig, en HEAD ook. Een server kan nog steeds een regel naar zijn log schrijven of het bezoek tellen; veilig betekent dat de client niet om een wijziging vroeg en er niet verantwoordelijk voor kan worden gehouden.

Idempotent

Een methode is idempotent als hetzelfde verzoek twee keer versturen de server in dezelfde toestand achterlaat als het één keer versturen. Het tweede verzoek kan een ander antwoord krijgen, en dat is prima: idempotentie gaat over de toestand, niet over de antwoorden.

Neem een leeslijst, een server die een lijst boeken bijhoudt, elk met een nummer. DELETE /books/7 verwijdert boek 7. Verstuur het nog eens en boek 7 is nog steeds weg; verder veranderde er niets. Dus DELETE is idempotent, al is het niet veilig: het eerste verzoek veranderde de lijst wel.

PUT /books/7 met een body maakt boek 7 precies gelijk aan die body. Verstuur het twee keer en boek 7 bevat hoe dan ook dezelfde body, dus PUT is ook idempotent.

POST /books met een body vraagt de server een boek toe te voegen en er een nummer voor te kiezen. Verstuur het twee keer en de lijst bevat twee nieuwe boeken. POST is veilig noch idempotent.

De vijf methoden

Elke veilige methode is ook idempotent: een verzoek dat niets verandert, laat dezelfde toestand achter, hoe vaak je het ook verstuurt. Andersom geldt dat niet, zoals PUT en DELETE laten zien.

Waarom een client dit belangrijk vindt

Soms verstuurt een client een verzoek en komt het antwoord nooit. De verbinding breekt, of de time-out van de client loopt af. De client kan niet zien of de server het verzoek nooit kreeg, of het wel kreeg, ernaar handelde en het antwoord onderweg terug kwijtraakte.

Voor een GET maakt die vraag niet uit: verstuur het opnieuw, en in het ergste geval leest de server hetzelfde boek twee keer. Voor een PUT of een DELETE maakt het ook niet uit, omdat een tweede exemplaar dezelfde toestand achterlaat als het eerste. Voor een POST maakt het heel veel uit: als het eerste verzoek wel aankwam, voegt opnieuw versturen het boek een tweede keer toe. Een client mag een veilig of idempotent verzoek dus herhalen na een verloren antwoord, en mag een POST niet herhalen zonder een andere manier om te weten of de eerste aankwam. Hoofdstuk 5 komt hierop terug: je eigen server accepteert daar POST en PUT, en je tests laten zien dat een herhaalde POST een tweede boek toevoegt, terwijl een herhaalde PUT niets meer verandert.

Een methode kiezen

De tabel werkt ook andersom: begin bij wat je gedaan wilt hebben en kies de methode waarvan de beloften passen. Iets lezen is GET, of HEAD als de kop genoeg is. Iets vervangen op een URL die je al kent, is PUT. Het verwijderen is DELETE. Iets nieuws toevoegen waarvan de server de URL bepaalt, is POST.

De methode is het eerste woord van de verzoekregel. Het tweede woord is het doel, dat je tot nu toe met de hand hebt getypt. De volgende les haalt een hele URL uit elkaar en laat zien waar elk deel naartoe gaat.