Het afsprakenstelsel maakt gebruik van HTTP(s) communicatie, beveiligd met TLS. HyperText Transfer Protocol (HTTP) is een communicatieprotocol voor internet en andere computernetwerken. Hiermee is het afsprakenstelsel in lijn met de API strategie voor de Nederlandse Overheid, het iSHARE (v2.0) en het Centre of Excellence for Data Sharing and Cloud (CoE-DSC) Use Case Implementation Guide die gebaseerd zijn op deze zelfde standaarden.

Partijen MOETEN in de context van datadiensten communiceren via het HTTP procotol

In het hoofdstuk informatiebeveiliging staan op de pagina’s Transport Layer Security en Public Key Infrastructure (PKI) en X.509 gedetailleerdere eisen voor de toepassing van TLS om communicatie via het HTTP te beveiligen.

HTTP Headers

In het DSGO wordt informatie voor identificatie, authenticatie en autorisatie verzonden wordt in HTTP headers. Daarom moeten grote HTTP-headers worden geaccepteerd.

Bron: iSHARE (v2.0) - HTTP(s)

iSHARE authentication/authorisation data is generally transferred in HTTP Headers. These headers can become very large when containing multiple encrypted certificates or JWT’s. iSHARE parties SHOULD configure their web servers to accept HTTP headers of larger sizes (usually 10K or more) to minimise implementation impact on current services.

Partijen MOETEN HTTP-headers van minimaal 10K lengte accepteren

HTTP Status codes

HTTP definieert standaard statuscodes die gebruikt moeten worden bij het antwoorden op een API verzoek. Deze worden beschreven in onderstaande tabel:

HTTP statuscode	Toelichting
`200 OK`	Reactie op een succesvolle `GET`, `PUT`, patch of `DELETE`. Ook geschikt voor `POST` die niet resulteert in een creatie
`201 Created`	Reactie op een `POST` die resulteert in een creatie. Moet worden gecombineerd met een locatie-header die wijst naar de locatie van de nieuwe resource
`204 No Content`	Reactie op een succesvol verzoek die geen inhoud zal teruggeven (zoals een `DELETE`)
`304 Not Modified`	Gebruikt wanneer HTTP caching headers worden toegepast
`400 Bad Request`	Het verzoek is onjuist, bijvoorbeeld als het verzoek (body) niet kan worden geïnterpreteerd
`401 Unauthorized`	Als er geen of ongeldige authenticatie details worden verstrekt. Ook handig om een authenticatie-venster te tonen als de API wordt gebruikt vanuit een browser
`403 Forbidden`	Als de authenticatie gelukt is maar de geverifieerde gebruiker geen toegangsrechten heeft voor de resource
`404 Not Found`	Wanneer een niet-bestaande resource is opgevraagd
`405 Method Not Allowed`	Wanneer een HTTP-methode wordt gebruikt die niet is toegestaan voor de geauthentiseerde gebruiker
`406 Not Acceptable`	Wordt teruggegeven als het gevraagde formaat niet ondersteund wordt (onderdeel van content negotiation)
`409 Conflict`	Het verzoek kon ik niet worden verwerkt als het gevolg van een conflict met de huidige toestand van de resource
`410 Gone`	Geeft aan dat de resource niet langer op het eindpunt beschikbaar is. Nuttig als een overkoepelend antwoord voor oude API versies
`412 Precondition Failed`	De preconditie die wordt gegeven door één of meer velden in de request-header, ontbraken of zijn na validatie op de server afgekeurd
`415 Unsupported Media Type`	Als een verkeerd content-type als onderdeel van het verzoek werd meegegeven
`422 Unprocessable Entity`	Gebruikt voor een verzoek (body) dat correct is maar dat de server niet kan verwerken
`429 Too Many Requests`	Wanneer een aanvraag wordt afgewezen als het aantal verzoeken per tijdsperiode is overschreden
`500 Internal Server Error`	Wanneer een onverwachte fout optreedt en het beantwoorden van het verzoek wordt verhinderd
`503 Service Unavailable`	Wordt gebruikt als de API niet beschikbaar is (bijv. door gepland onderhoud)

Bron: API strategie voor de Nederlandse Overheid - HTTP statuscodes

HTTP definieert een hele reeks gestandaardiseerde statuscodes die gebruikt dienen te worden door API's. Deze helpen de gebruikers van de API's bij het afhandelen van fouten. Zie tabel hieronder met een samenvatting van HTTP-operaties in combinatie met de primaire HTTP statuscodes. In de tabel daaronder en korte lijst met een beschrijving van de HTTP statuscodes die minimaal worden toegepast:

Operatie	CRUD	Gehele collectie (bijvoorbeeld /resource)	Specifieke item (bijvoorbeeld `/resource/\<id>`)
`POST`	Create	201 (Created), HTTP header `Location` met de URI van de nieuwe resource (`/resource/\<id>`)	405 (Method Not Allowed), 409 (Conflict) als de resource al bestaat
`GET`	Read	200 (OK), lijst van resources. Gebruik pagineren, filteren en sorteren om het werken met grote lijsten te vereenvoudigen	200 (OK) enkele resource, 404 (Not Found) als ID niet bestaat of ongeldig is
`PUT`	Update	405 (Method Not Allowed), behalve als het de bedoeling is om toe te staan elke resource in een collectie te vervangen	200 (OK) of 204 (No Content), 404 (Not Found) als ID niet bestaat of ongeldig is
`PATCH`	Update	405 (Method Not Allowed), behalve als het de bedoeling is om toe te staan de gehele collectie te wijzigen.	200 (OK) of 204 (No Content), 404 (Not Found) als ID niet bestaat of ongeldig is
`DELETE`	Delete	405 (Method Not Allowed), behalve als het de bedoeling is toe te staan de gehele collectie te verwijderen	200 (OK) of 404 (Not Found) als ID niet bestaat of ongeldig is

Partijen MOETEN bij het ontvangen van een HTTP-verzoek antwoorden met (onder andere) een statuscode die het resultaat van het verzoek aangeeft

Partijen MOETEN geschikte HTTP-statuscodes ondersteunen die passen bij de dienst. Tenminste de volgende: 2XX, 4XX en 5XX

Partijen ZOUDEN de standaard foutmeldingen van de HTTP 400 en 500 statuscode reeksen MOETEN ondersteunen volgens RFC 9110