HTTP(s)

Het afsprakenstelsel maakt gebruik van HTTP(s) communicatie, beveiligd met TLS. HyperText Transfer Protocol (HTTP) is een communicatieprotocol voor internet en andere computernetwerken.

DSGO.Basis: Partijen MOETEN in de context van datadiensten communiceren via het HTTP protocol

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.

DSGO.Basis: 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

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)

Operatie

CRUD

Gehele collectie (bijvoorbeeld /resource)

Specifieke item (bijvoorbeeld /resource/\<id>)

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