Dit document valt onder de volgende licentie:
Creative Commons Attribution 4.0 International Public License
Deze hypermedia module is gebaseerd op het hypermedia hoofdstuk van het NL API Strategie extensies document
Dit is de definitieve conceptversie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.
Dit onderdeel is niet normatief.
Dit Hoofdstuk geeft een inleiding op de Nederlandse API strategie. De stategie is opgebouwd uit meerdere documenten, standaarden en modulen. De NL API Strategie wordt doorontwikkeld en beheerd door het Kennisplatform API's.
Op GitHub kan bekeken worden wat de actuele ontwikkelingen zijn met betrekking tot de Nederlandse API strategie.
Er worden slechts een beperkt aantal auteurs genoemd, echter aan deze strategie is door veel meer mensen gewerkt. Per onderdeel van de API strategie staan de degene verantwoordelijk voor de laatste versie vermeld. De genoemde auteurs zijn deelnemers aan de relevante werkgroep van het Kennisplatform API's zoals: API Strategie, Architectuur, Security, Design Rules, Authenticatie en Autorisatie, Strategie en Beleid, en Gebruikerswensen.
De API strategie bestaat uit een een inleidend document, verschillende normatieve documenten (NL GOV standaarden) en meerdere modulen die voor verschillende functionele of technische situaties kunnen worden ingezet. Een actueel overzicht van alle documenten is weergegeven in de onderstaande infographic:
De verschillende onderdelen van de NL API Strategie bevat de volgende documenten:
Onderdeel | Documentnaam & Verwijzing naar de gepubliceerde versie |
Status | Versie |
---|---|---|---|
Algemeen | Inleiding NL API Strategie | Vastgesteld (door Kennisplatform) |
09-03-2022 |
Algemeen | Architectuur NL API Strategie | Vastgesteld (door Kennisplatform) |
09-03-2022 |
Algemeen | Gebruikerswensen NL API Strategie | Vastgesteld (door Kennisplatform) |
09-03-2022 |
Normatieve standaard | API Design Rules (ADR) | Verplicht (pas toe leg uit) |
09-07-2020 v1.0.0 |
Verplichte standaard | Open API Specification (OAS) | Verplicht (pas toe leg uit) |
25-05-2018 v3.0.0 |
Normatieve standaard | NL GOV OAuth profiel | Verplicht (pas toe leg uit) |
09-07-2020 v1.0.0 |
Voorgestelde standaard | NL GOV OpenID Connect profile | Verplicht (pas toe leg uit) |
18-02-2021 v1.0.0 |
Verplichte standaard | Digikoppeling REST API koppelvlak specificatie | Verplicht (pas toe leg uit) |
14-11-2022 v1.1.1 |
Aanvullende module | API Geospatial Design Rules module | Vastgesteld * (door Kennisplatform) |
23-05-2023 |
Aanvullende module | API Transport Security module | Stabiel * (Werkgroep Kennisplatform) |
11-07-2023 |
Aanvullende module | API Access control module | Stabiel (Werkgroep Kennisplatform) |
11-07-2023 |
Aanvullende module | API Naming conventions module | Stabiel (Werkgroep Kennisplatform) |
12-07-2023 |
Aanvullende module | API Hypermedia module | Stabiel (Werkgroep Kennisplatform) |
12-07-2023 |
Hypermedia relates to the use of hyperlinks (from now on called links) as part of a document's payload, which are essentially URIs pointing to other resources. Typically, but not necessarily, these links are retrievable (also called dereferencable) from the web over the HTTP protocol. We intentionally make a clear separation between navigation controls and external links. Both kinds can easily be combined as part of a single API.
/hypermedia/absolute-uris: Provide absolute URIs for hyperlinks
Only absolute URIs MAY be provided since this enables simple traversal of links by following URIs. While relative links are more compact and may be practical when having multi-environment deployments, they introduce extra complexity for the client and may potentially result in erroneous behaviour (e.g. when dealing with trailing slashes or dot segments). For the same reasons, absolute URIs MAY not be templated.
This design rule does explicitly NOT intend the use of hyperlinks as an implementation of the often debated HATEOAS constraint, as described in the well-known REST thesis (Roy Fielding) or the Richardson Maturity Model (Level 3). An API specification must offer a strict and stable contract between server and client, which should guarantee backwards compatiblity during the full lifetime of a given major version, whereas true HATEOAS advocates continually evolving interfaces requiring little to no prior knowledge about how to interact with the application.
External links are references to URIs outside of the scope of the originating API. These links can point to literally any location on the web; they may even point to URIs which are not dereferencable at all (e.g. in case they are used as a universal identifier only). A few examples:
/hypermedia/external-links: Treat external links as regular resource attributes
External links MUST be considered in the same way as regular resource attributes.
For example, a book resource may provide a link to the cover image:
{
"identifier": "14d3030c-3b61-4070-b902-342f80e99364",
"title": "Da Vinci Code",
"isbn": "902455991X",
"cover": "https://cdn.example.org/covers/davincicode.png",
"website": "https://danbrown.com/the-davinci-code/",
"_links": {
"self": {
"href": "https://api.example.org/v1/books/14d3030c-3b61-4070-b902-342f80e99364"
}
}
}