RESTful API's

Het afsprakenstelsel maakt gebruik van RESTful API's.

Wanneer een datadienst een gegronde reden heeft om af te wijken van een RESTful-implementatie om hun datadienst mogelijk te maken (bv. wegens legacy-beperkingen), is dit mogelijk. Daarom is deze eis een zou.

DSGO.Basis: Partijen ZOUDEN RESTful architectuurprincipes MOETEN volgen voor API’s

Introductie API's

Bron: API strategie voor de Nederlandse Overheid - 2.3 Wat is een API

Een Application Programming Interface (API) is een combinatie van technische bestanden, documentatie en andere ondersteuning die helpen bij het aanroepen van externe applicaties (Als het in deze API-strategie gaat over API’s dan bedoelen we daarmee RESTful API’s). Een API wordt gepubliceerd door een softwareontwikkelaar, zodat andere ontwikkelaars weten hoe de software te koppelen aan de eigen software. Zodoende kunnen twee applicaties rechtstreeks en online met elkaar communiceren. Het is daarmee geen standaard, maar eerder een handleiding die kan worden gebruikt voor een machine tot machine koppeling. Met name daar waar veel digitale diensten met elkaar samenwerken en informatie realtime op een makkelijke en toegankelijke manier willen delen zijn API’s zeer geschikt. De belangrijke eigenschappen van moderne API’s zijn:

  • prestaties (het zorgt ervoor dat machines snel met elkaar praten);

  • schaalbaarheid (het zorgt ervoor dat het blijft werken bij veel gebruik(ers);

  • simpele interfaces (de communicatie tussen componenten is eenvoudig en overzichtelijk).

API’s kunnen gezien worden als ‘proven technology’, er is veel kennis over en ervaring mee in de markt. Berichten uitwisselen via API’s is niet perse onveiliger of veiliger dan hoe de overheid op dit moment haar berichtenuitwisseling organiseert. Het gebruik van API’s beperkt zich daarmee niet alleen tot open data, maar kan juist ook goed worden ingezet voor meer gevoelige / gesloten data.

RESTful principes

Bij het gebruik van RESTful API's is het van belang dat logische resources gescheiden zijn. Resources kunnen worden gemanipuleerd (middels een datadienst) met HTTP-operaties.

Bron: API strategie voor de Nederlandse Overheid - 4.2 RESTful principes

Het belangrijkste principe van REST is het scheiden van de API in logische resources ("dingen"). De resources beschrijven de informatie van het "ding". Deze resources worden gemanipuleerd met behulp van HTTP-verzoeken en HTTP-operaties. Elke operatie (GET, POST, PUT, PATCH, DELETE) heeft een specifieke betekenis, zie onderstaande tabel.

HTTP definieert ook operaties als HEAD, TRACE, OPTIONS en CONNECT. Deze worden echter in de context van REST vrijwel niet gebruikt en zijn daarom in de verdere uitwerking weggelaten.

Operatie

CRUD

Toelichting

Operatie

CRUD

Toelichting

POST

Create

Wordt gebruikt als een "create" voor resources (ofwel POST voegt een resource toe aan de collectie).

GET

Read

Wordt gebruikt om een resource op te vragen van de server. Data wordt alleen opgevraagd en niet gewijzigd.

PUT

Update

Wordt gebruikt om een specifieke resource te vervangen. Is óók een "create" wanneer de resource op aangegeven identifier/URI nog niet bestaat.

PATCH

Update

Wordt gebruikt om een bestaande resource gedeeltelijk bij te werken. Het verzoek bevat de gegevens die gewijzigd moeten worden en de operaties die de resource muteren in het daarvoor bedoelde JSON merge patch formaat (RFC 7386).

DELETE

Delete

Verwijdert een specifieke resource.

Resources

Binnen het Afsprakenstelsel wordt data als resources beschikbaar gesteld.

Request

Omschrijving

Request

Omschrijving

GET /aanvragen

Haalt een lijst van aanvragen op

GET /aanvragen/12

Haalt aanvraag #12 op

POST /aanvragen

Creëert een nieuwe aanvraag

PUT /aanvragen/12

Wijzigt aanvraag #12 als geheel

PATCH /aanvragen/12

Wijzigt een gedeelte van aanvraag #12

DELETE /aanvragen/12

Verwijdert aanvraag #12

Â