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 |
---|---|---|
| Create | Wordt gebruikt als een "create" voor resources (ofwel |
| Read | Wordt gebruikt om een resource op te vragen van de server. Data wordt alleen opgevraagd en niet gewijzigd. |
| Update | Wordt gebruikt om een specifieke resource te vervangen. Is óók een "create" wanneer de resource op aangegeven identifier/URI nog niet bestaat. |
| 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 | Verwijdert een specifieke resource. |
DSGO.Basis
: Partijen MOETEN uitsluitend standaard HTTP-operaties ondersteunen (GET, PUT, POST, PATCH, DELETE)
DSGO.Basis
: Partijen MOGEN NIET de state van de client bij houden
Resources
Binnen het Afsprakenstelsel wordt data als resources beschikbaar gesteld.
DSGO.Basis
: Partijen MOETEN data als resources beschikbaar stellen in een datadienst
DSGO.Basis
: Partijen MOETEN resources een zelfstandig naamwoord in het meervoud als naam geven
Bron: API strategie voor de Nederlandse Overheid - 4.2.1 Wat zijn resources?
Het fundamenteel concept in elke RESTful API is de resource. Een resource is een object met een type, bijbehorende data, relaties met andere resources en een aantal operaties om deze te bewerken. Resources worden aangeduid met zelfstandige naamwoorden (niet werkwoorden!) die relevant zijn vanuit het perspectief van de afnemer van de API. Dus resources zijn zelfstandige naamwoorden en operaties zijn werkwoorden. Operaties zijn acties die op resources worden uitgevoerd.
Het is mogelijk om interne datamodellen één-op-één toe te wijzen aan resources, maar dit hoeft niet per definitie zo te zijn. De crux is om alle niet relevante implementatiedetails te verbergen. Enkele voorbeelden van resources zijn: aanvraag, activiteit, pand, rijksmonument en vergunning.
Als de resources geïdentificeerd zijn, wordt bepaald welke operaties van toepassing zijn en hoe deze worden ondersteund door de API. RESTful API's realiseren CRUD (Create, Read, Update, Delete) operaties met behulp van HTTP-operaties, zie tabel hieronder.
Het mooie van REST is dat er gebruik wordt gemaakt van de bestaande HTTP-operaties om de functionaliteit te implementeren met één enkel eindpunt. Hierdoor zijn er geen aanvullende naamgevingsconventies nodig in de URI en blijft de URIstructuur eenvoudig.
Request | Omschrijving |
---|---|
| Haalt een lijst van aanvragen op |
| Haalt aanvraag #12 op |
| Creëert een nieuwe aanvraag |
| Wijzigt aanvraag #12 als geheel |
| Wijzigt een gedeelte van aanvraag #12 |
| Verwijdert aanvraag #12 |