Hypermedia Module

Geonovum Handreiking
Versie ter vaststelling

Deze versie:
https://docs.geostandaarden.nl/api/vv-hr-API-Strategie-mod-hypermedia-20231221
Laatst gepubliceerde versie:
https://docs.geostandaarden.nl/api/API-Strategie-mod-hypermedia/
Laatste werkversie:
https://geonovum.github.io/KP-APIs/API-strategie-modules/hypermedia/
Vorige versie:
https://docs.geostandaarden.nl/api/API-Strategie-ext/#hypermedia
Redacteur:
Kennisplatform API's (Kennisplatform API's)
Auteur:
Kennisplatform API's (Kennisplatform API's)
Doe mee:
GitHub Geonovum/KP-APIs
Dien een melding in
Revisiehistorie
Pull requests

Samenvatting

Deze hypermedia module is gebaseerd op het hypermedia hoofdstuk van het NL API Strategie extensies document

Status van dit document

Dit is de definitieve conceptversie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.

1. Inleiding van de NL API strategie

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.

1.1 Status

Op GitHub kan bekeken worden wat de actuele ontwikkelingen zijn met betrekking tot de Nederlandse API strategie.

1.2 Auteurs

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.

1.3 Leeswijzer

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:

Figuur 1 NL API Strategie 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

2. Hypermedia

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.

Noot

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.

A. Referenties

A.1 Informatieve referenties

[HAL]
HAL - Hypertext Application Language. Mike Kelly. 2013-09-18. URL: http://stateless.co/hal_specification.html
Geonovum Handreiking - Versie ter vaststelling