API afspraken

Algemene afspraken

• De data de die met de API's worden ontsloten zijn publieke data en deze dient laagdrempelig direct toegankelijk te zijn.
• We onderkennen 2 type API's. Generieke teksten API's (van de Nationale Portalen (NP)) en Specifieke teksten API's (van de Decentrale Overheden (DO))

Welke standaarden zijn gevolgd

Dit resulteert in een gestandaardiseerde API die gebaseerd dient te zijn op:

• De OpenAPI Specification en
• De REST-API Design Rules.

SDG informatiemodel

De API specificatie is gebaseerd op het SDG informatiemodel.

De OAS voldoet aan de volgende eisen:

• de naamgeving van de attributen volgt de naamgeving in het informatiemodel
• ieder attribuut volgt het formaat voorgeschreven in de informatiemodel.
• ieder attribuut wordt voorzien van een description en example

De actuele versie van het SDG informatiemodel is te vinden op de Teams omgeving van bNC (ICTU). Voor eenvoudige naslag hier het Informatie model 1.5.xlsx. Het versienummer is welliswaar 1.5, maar inhoudelijk is dit hetzelfde als 1.4. Verschil is dat deze 1.5 versie een bijgewerkt class-diagram bevat.

Non-functionals

Beveiliging API

De Producten API ontsluit de productbeschrijvingen naar de nationale portalen en mogelijk ook naar gemeenten en andere geïnteresseerden. De productbeschrijvingen zijn publieke data.

• De Producten API is publiek toegankelijk om te lezen

Afnemers moeten de zekerheid hebben dat zij de door gemeenten beheerde teksten ophalen

• De Producten API authenticeert zichzelf met een certificaat, opdat de Nationale portalen de zekerheid hebben productteksten van gemeenten te publiceren.
• De NP halen daartoe gegevens op bij het domein vng.nl
• We accepteren alleen TLS 1.2 & 1.3 & door het NCSC goedgekeurde cipher suites (overeenkomstig de digikoppeling security @@@document verwijzing)
• SSL Labs geeft een minimale score van "A"
• Internet.nl geeft een minimale site score van 80%
  • IPv6 wordt nu door de invoervoorziening niet ondersteund. Nog nader te bepalen of dit een eis is.

Snelheid

• Anonieme afnemers hebben geen garantie op responstijd
• Bekende afnemers (met API key) kunnen onbeperkt opvragen met een gegarandeerde responsetijd:
  • Enkelvoudige opvragingen (één product van één gemeente) maximaal 0,1 seconden
  • Meervoudige opvragingen maximaal 0,5 seconden

Capaciteit

• Anonieme afnemers kunnen onbeperkt opvragen, maar worden bij grote aantallen in de snelheid geknepen.
• Aan bekende afnemers (voor nu 4 portalen) moet kunnen worden gegarandeerd dat 10 productbeschrijvingen per seconde kunnen worden opgehaald. Deze eisen gelden als de voorlopige eisen, totdat deze op basis van daadwerkelijke gebruik gegevens kunnen worden vastgesteld.

Endpoints

• Er is per DO (koepel) één endpoint voor alle organisaties en beide talen.
• Er is per NP één endpoint voor beide talen
• We onderkennen 2 aanbieders van Generieke teksten API's (DOP & DPC)
• We onderkennen 3 aanbieders van Specifieke teksten API's (VNG, IPO, UVW)
• in totaal dus 5 endpoint

Testen

• De API is te testen/proberen via Swagger en de wens is nog om een publieke postman collectie op te zetten om te testen?
• testscripts van een API (bv. postman collectie) worden tussen de partijen gedeeld
• De API's kunnen door de partijen over en weer worden getest in een ketentestomgeving.
  • bij voorkeur is de ketentestomgeving gelijk aan de acceptatieomgeving.

API open vraagstukken

• publicatie API op developer.overheid.nl?
• Is IPV6 een eis?