Free Press

REST APIs stellen u in staat om elk soort web applicatie te ontwikkelen met alle mogelijke CRUD (create, retrieve, update, delete) operaties. REST richtlijnen suggereren het gebruik van een specifieke HTTP methode voor een bepaald type aanroep aan de server (hoewel het technisch mogelijk is om deze richtlijn te overtreden, maar het wordt sterk afgeraden).

Gebruik onderstaande informatie om een geschikte HTTP methode te vinden voor de actie uitgevoerd door API.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

Gebruik GET requests om alleen bronrepresentatie/informatie op te halen – en niet om deze op enige manier te wijzigen. Aangezien GET-verzoeken de toestand van de bron niet veranderen, worden dit veilige methoden genoemd. Bovendien moeten GET API’s idempotent zijn, wat betekent dat het doen van meerdere identieke verzoeken telkens hetzelfde resultaat moet opleveren totdat een andere API (POST of PUT) de toestand van de bron op de server heeft gewijzigd.

Als de Request-URI verwijst naar een gegevensproducerend proces, zijn het de geproduceerde gegevens die moeten worden geretourneerd als de entiteit in de respons en niet de brontekst van het proces, tenzij die tekst toevallig de output van het proces is.

Voor elke HTTP GET API geldt dat als de bron op de server wordt gevonden, deze HTTP-responscode 200 (OK) moet retourneren – samen met de responsbody, die gewoonlijk bestaat uit XML- of JSON-inhoud (vanwege hun platformonafhankelijke aard).

In het geval dat de bron NIET op de server wordt gevonden, moet deze HTTP-responscode 404 (NOT FOUND) retourneren. Ook als wordt vastgesteld dat het GET-verzoek zelf niet correct is geformuleerd, stuurt de server HTTP-antwoordcode 400 (BAD REQUEST) terug.

Exemplarisch verzoek URI’s

• HTTP GET http://www.appdomain.com/users
• HTTP GET http://www.appdomain.com/users?size=20&page=5
• HTTP GET http://www.appdomain.com/users/123
• HTTP GET http://www.appdomain.com/users/123/adres

HTTP POST

Gebruik POST API’s om nieuwe ondergeschikte bronnen aan te maken, bijv, een bestand is ondergeschikt aan een directory die het bevat of een rij is ondergeschikt aan een database tabel. Wanneer strikt in termen van REST wordt gesproken, worden POST-methoden gebruikt om een nieuwe bron in de verzameling bronnen te creëren.

In het algemeen, als een bron op de origin server is gecreëerd, DIENT het antwoord HTTP-responscode 201 (Created) te zijn en een entiteit te bevatten die de status van het verzoek beschrijft en naar de nieuwe bron verwijst, alsmede een Location header.

Vaak zal de actie die door de POST-methode wordt uitgevoerd, niet resulteren in een bron die met een URI kan worden geïdentificeerd. In dat geval is HTTP-responscode 200 (OK) of 204 (No Content) de juiste responsstatus.

Respons op deze methode kan niet in de cache worden opgeslagen, tenzij het antwoord de juiste Cache-Control- of Expires-headervelden bevat.

Let erop dat POST veilig noch idempotent is, en dat het inroepen van twee identieke POST-verzoeken zal resulteren in twee verschillende bronnen die dezelfde informatie bevatten (met uitzondering van bron-id’s).

Exemplarisch verzoek URI’s

• HTTP POST http://www.appdomain.com/users
• HTTP POST http://www.appdomain.com/users/123/accounts

HTTP PUT

Gebruik PUT API’s in de eerste plaats om bestaande bronnen te updaten (als de bron niet bestaat, kan de API besluiten om al dan niet een nieuwe bron aan te maken). Indien een nieuwe bron is aangemaakt door de PUT API, MOET de origin server de user agent daarvan op de hoogte brengen via de HTTP-responscode 201 (Created) en indien een bestaande bron wordt gewijzigd, ZOU de responscode 200 (OK) of 204 (No Content) moeten worden verzonden om aan te geven dat het verzoek met succes is voltooid.

Indien het verzoek door een cache gaat en de Request-URI een of meer momenteel in de cache opgeslagen entiteiten identificeert, MOETEN deze entiteiten als oud worden behandeld. Antwoorden op deze methode kunnen niet in een cache worden opgeslagen.

Voorbeeld request URI’s

• HTTP PUT http://www.appdomain.com/users/123

HTTP DELETE

Zoals de naam al zegt, worden DELETE API’s gebruikt om bronnen te verwijderen (geïdentificeerd door de Request-URI).

Een succesvol antwoord op DELETE-verzoeken ZOU HTTP-respons code 200 (OK) MOETEN zijn als het antwoord een entiteit bevat die de status beschrijft, 202 (Accepted) als de actie in de wachtrij is geplaatst, of 204 (No Content) als de actie is uitgevoerd maar het antwoord geen entiteit bevat.

DELETE-bewerkingen zijn idempotent. Als u een bron DELETE, wordt het verwijderd uit de verzameling van bronnen. Het herhaaldelijk oproepen van de DELETE API op die bron zal het resultaat niet veranderen – echter, het een tweede keer oproepen van DELETE op een bron zal een 404 (NOT FOUND) teruggeven omdat het al verwijderd was. Sommigen zullen aanvoeren dat dit de DELETE methode niet-idempotent maakt. Dat is een kwestie van discussie en persoonlijke opvatting.

Als het verzoek door een cache gaat en de Request-URI een of meer momenteel in de cache opgeslagen entiteiten identificeert, MOETEN die entiteiten als oud worden behandeld. Antwoorden op deze methode zijn niet cacheable.

Voorbeeld request URIs

• HTTP DELETE http://www.appdomain.com/users/123
• HTTP DELETE http://www.appdomain.com/users/123/accounts/456

HTTP PATCH

HTTP PATCH verzoeken zijn om een gedeeltelijke update van een resource te maken. Als je ziet PUT verzoeken ook een resource entiteit wijzigen, dus om meer duidelijk te maken – PATCH methode is de juiste keuze voor het gedeeltelijk bijwerken van een bestaande resource, en PUT moet alleen worden gebruikt als je een resource vervangt in zijn geheel.

Merk op dat er een aantal uitdagingen zijn als u besluit om PATCH API’s te gebruiken in uw toepassing:

• Support voor PATCH in browsers, servers, en webapplicatie frameworks is niet universeel. IE8, PHP, Tomcat, Django en vele andere software bieden geen of gebrekkige ondersteuning.
• De payload van een PATCH-verzoek is niet rechttoe rechtaan zoals bij een PUT-verzoek. bijv.

  HTTP GET /users/1

  levert het volgende antwoord op:

  {id: 1, username: 'admin', email: ''}

  Een voorbeeld van een patchverzoek om de e-mail bij te werken ziet er als volgt uit:

  HTTP PATCH /users/1

  ” }
  ]

Er zijn de volgende mogelijke operaties volgens de HTTP-specificatie.

},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]

De PATCH-methode is geen vervanging voor de POST- of PUT-methoden. Het past een delta (diff) toe in plaats van de gehele bron te vervangen.

Samenvatting van HTTP-methoden voor RESTful API’s

De onderstaande tabel geeft een overzicht van het gebruik van HTTP-methoden die hierboven zijn besproken.

Glossary

Safe Methods

Volgens de HTTP-specificatie mogen de methoden GET en HEAD alleen worden gebruikt voor het opvragen van bronrepresentaties – en ze actualiseren/verwijderen de bron niet op de server. Van beide methoden wordt gezegd dat ze als “veilig” worden beschouwd.

Dit stelt user agents in staat om andere methoden, zoals POST, PUT en DELETE, op een unieke manier weer te geven, zodat de gebruiker bewust wordt gemaakt van het feit dat een mogelijk onveilige actie wordt gevraagd – en ze kunnen de bron op de server bijwerken/verwijderen en moeten dus zorgvuldig worden gebruikt.

Idempotent Methods

De term idempotent wordt meer in het algemeen gebruikt om een bewerking te beschrijven die dezelfde resultaten zal opleveren als ze een of meerdere keren wordt uitgevoerd. Idempotent is een handige eigenschap in veel situaties, omdat het betekent dat een bewerking zo vaak als nodig herhaald of opnieuw uitgevoerd kan worden zonder onbedoelde effecten te veroorzaken. Bij niet-idempotente operaties kan het algoritme moeten bijhouden of de operatie al is uitgevoerd of niet.

In de HTTP-specificatie zijn de methoden GET, HEAD, PUT en DELETE als idempotente methoden gedeclareerd. Andere methoden OPTIONS en TRACE ZOUEN GEEN neveneffecten hebben, dus beide zijn ook inherent idempotent.