7.4: Transport OpenAPI
7.4 Transport / OpenAPI
7.4.1 OpenAPI model
Vanaf begin 2024 is gewerkt aan een standaard voor het transport van de berichten. Een aantal PUO's en vermogensbeheerders hebben in samenwerking met SIVI stappen gezet in de ontwikkeling van een OpenAPI-specificatie binnen de eerder geschetste technische contouren.
Deze inspanning beoogde zowel de ondersteuning van alle partijen die de RESTful API zullen implementeren als het bevorderen van een uniforme toepassing ervan. De specificatie is te vinden op GitHub. De voorgestelde OpenAPI-specificatie helpt partijen bij het eenduidig uitwisselen van de berichtstructuren, zowel voor SPR als voor FPR. Naast de inhoudelijke berichten is ook een feedbackbericht gerealiseerd waarmee gereageerd kan worden op de inhoudelijke berichten.
De API fungeert als een digitaal loket, waarmee de verschillende PUO- en vermogensbeheerpartijen data kunnen ontvangen. De communicatie vindt plaats op initiatief van de verzendende partij (push-model); de verzendende partij levert de berichten aan bij de ontvangende partij zonder dat deze hier actief om hoeft te vragen. De specificatie begint met algemene informatie, waarin de naam, beschrijving en versie van de API staan vermeld.
De kern van de API beschrijft de specifieke services die beschikbaar zijn. Voor elke service is er een duidelijk pad gedefinieerd waarop berichten kunnen worden afgeleverd. Dit omvat bijvoorbeeld het aanleveren van informatie of het uitvoeren van bepaalde handelingen. Elk pad biedt een beschrijving van wat de dienst doet en hoe deze gebruikt kan worden.
Let op, in de praktijk zal niet iedere partij alle services uit de OAS aan. Partijen die alleen SPR voeren kunnen bijvoorbeeld, naast het feedbackbericht de berichten de SPR-berichten 1, 2, 3 en 4 aanbieden.
Daarnaast bevat de specificatie herbruikbare bouwstenen, zoals berichten en entiteiten. Dit zorgt ervoor dat de API consistent is en gemakkelijk te begrijpen en te gebruiken. Door het hergebruik van deze berichten en entiteiten wordt ontwikkeling eenvoudiger en de kans op fouten verminderd.
Om de volledigheid en integriteit van de berichten te waarborgen, is een mechanisme geïntroduceerd dat controle mogelijk maakt op wijzigingen tijdens transport. Het gaat om een zogenaamde x-jws-signature header, die een digitale handtekening van de payload bevat. Dit biedt een betrouwbare basis voor partijen om erop te vertrouwen dat ontvangen berichten exact overeenkomen met wat is verzonden. Het gebruik van dit middel is een mogelijkheid, geen verplichting. Partijen kunnen afwijkende keuzes maken.
Belangrijk is dat de standaard uitsluitend ondersteuning biedt voor de OAS API; andere vormen van gegevensuitwisseling worden niet ondersteund. Dit betekent dat alle communicatie tussen partijen volgens de gespecificeerde OpenAPI-specificatie dient te verlopen, en alternatieve methoden buiten de scope van de standaard vallen.
Beveiligingsmaatregelen API:
De belangrijkste beveiligingsmaatregelen zijn als volgt:
| Beveiligingsmaatregel | Beschrijving |
|---|---|
| Authenticatie met API-sleutel | Elke aanvraag moet een geldige API-sleutel bevatten in de x-api-key header. Dit voorkomt ongeoorloofde toegang tot de API. |
| OAuth 2.0 Client Credentials Flow | De API maakt gebruik van OAuth 2.0 voor authenticatie en autorisatie. Clients moeten een toegangstoken verkrijgen via de token endpoint met hun client-ID en geheim. |
| Specifieke scopes worden gebruikt om toegang tot verschillende API-functies te regelen, waardoor alleen geautoriseerde acties kunnen worden uitgevoerd. | |
| Digitale Handtekeningen met x-jws-signature (optie) | Als van dit mechanisme gebruik wordt gemaakt, dan bevat elke aanvraag een digitale handtekening van de payload in de x-jws-signature header. Dit stelt de ontvanger in staat om te verifiëren dat het bericht niet is gewijzigd tijdens transport. . |
| Versleutelde Communicatie via HTTPS | Alle communicatie verloopt via HTTPS, wat zorgt voor versleuteling van gegevens tijdens transmissie en bescherming tegen onderschepping. |
7.4.2 API-implementatie en back-up
Deployment en operationeel houden van de API's is de verantwoordelijkheid van de partij die de API aanbiedt en valt buiten het bereik van de standaard. (Tijdelijke) uitval van de API-gegevenstransportvoorziening kan voorkomen. Het risico daarop is kleiner bij een aanpak waarbij meerdere replica’s van de API gelijktijdig draaien (op verschillende omgevingen en/of locaties). Uiteindelijk is dit een kosten/baten afweging; het garanderen van een 99,9% uptime is kostbaarder dan een 98% uptime garantie.
Uitgangspunt is dat uitval steeds kortdurend zal zijn. In uitzonderingsgevallen kan email als “back-up” transportmechanisme gelden.