API strategie voor de Nederlandse overheid

3.4.1 Aanbeveling 1: werk met (meerdere) persona’s

Een API ontwerp en bouw je niet voor een machine, maar voor een gebruiker: een mens! Om een goede DX te bieden, moet je dus eerst weten voor wie je ontwerpt en bouwt, voordat je dat goed kunt doen. Persona’s zijn dan belangrijk, er is niet maar één type developer! Redeneer van buiten naar binnen: wie zijn mijn gebruikers, wat willen zij kunnen doen en wat moet ik doen om dat zo goed mogelijk te faciliteren. Het typeren van gebruikers en analyseren welke behoeften zij hebben, doe je op basis van persona’s.

Belangrijk hierbij is om te onderkennen dat er verschillende niveaus of typen gebruik zijn. Onderscheid daarom -met de fases van ‘onboarding’ tot ‘in productie’ in het achterhoofd- minimaal de volgende persona’s:

• een product manager / business developer: focus op het kunnen beoordelen van functionaliteit (“Is dit relevant voor mijn product / mijn doel?”)

• een architect: focus op het beoordelen van het informatiemodel (“Hoe integreert dit met de rest van onze software?”)

• een technische developer: focus op het daadwerkelijk kunnen gebruiken (“Hoe krijg ik dit werkend?”).

3.4.2 Aanbeveling 2: analyseer welke API’s je aan moet bieden: welke informatievragen wil je beantwoorden?

De ene API is de andere niet. In veel modellen worden API’s in drie categorieën onderverdeeld: de System API (die werkt op het niveau van de databron), de Process API (die doet aan orchestration door één of meerdere System API’s aan te roepen) en de Convenience of Experience API (die één specifieke gebruikersvraag beantwoord). Vraag je altijd af welke informatievragen de gebruiker heeft – in veel gevallen hangen deze vragen niet 1:1 samen met het datamodel.

Stel dat je de Basisregistratie Adressen en Gebouwen wil ontsluiten. De informatievraag “Geef me het volledige adres bij deze postcode” is alleen te beantwoorden door intern bij een Verblijfsobject de Openbare Ruimte naam, Nummeraanduiding en Woonplaats op te vragen en te combineren tot één adressering. Bij een System API moet je meerdere calls doen om dit adres op te bouwen, terwijl een Convenience API deze gangbare (maar complexe) vraag in één call kan beantwoorden. Het aanbieden van Convenience API’s naast System API’s is dus erg gebruiksvriendelijk: de 80% gebruikers die hiermee geholpen zijn, confronteer je met slechts 20% van de complexiteit. Vergelijk dit met de Toptaken-aanpak bij de websites van veel gemeenten: de meest aangevraagde producten (bijv. nieuw paspoort en rijbewijs) staan pontificaal op de homepage, terwijl de minder vaak gevraagde diensten op vervolgpagina’s staan. Zo reduceer je de complexiteit voor een zo groot mogelijk deel van je gebruikers.

3.4.3 Aanbeveling 3: documenteer gericht op de gebruiker, biedt snel inzicht en gebruik OAS 3

Elk type gebruiker dat in aanbeveling 1 wordt genoemd (business developer, architect, technische developer) verdient zijn eigen ‘Getting started’ documentatie, gericht op het snel kunnen beoordelen en/of toepassen. Documentatie is nooit een lijvig document (wanneer veel documentatie nodig lijkt, is de functionaliteit vermoedelijk te complex) én nooit een PDF: laat je gebruikers makkelijk klikken naar relevante onderdelen binnen én buiten de documentatie! Referentie-implementaties kunnen ook zinvol zijn om snel een indruk te bieden van functionaliteit. Voor de technische developer is de documentatie conform de Open API Specifiction 3.0 (OAS 3); deze staat in Nederland op de ‘Pas toe of leg uit-lijst’ van het Forum Standaardisatie.

3.4.4 Aanbeveling 4: minimaliseer Time to First Call met een goede Sandbox

Zorg dat een developer snel een werkend voorbeeld heeft. Dit vraagt om een goed gedocumenteerde, realistische Sandbox. Deze Sandbox dient alle aspecten van de API te ondersteunen en identiek gedrag aan de productieversie van de API te vertonen, bijvoorbeeld rond authenticatie. Daar waar mogelijk is het zeer wenselijk dat meerdere API’s dezelfde dataset bieden als Sandbox, zodat ook het samenspel tussen verschillende API’s getest kan worden.

3.4.5 Aanbeveling 5: borg ontwikkeling en beheer

Ook al is een API nog zo goed ontwikkeld, wanneer doorontwikkeling en beheer niet goed geregeld is, zal die API niet succesvol zijn. Essentieel hierin is dat je gebruikers duidelijkheid biedt:

3.4.6 Aanbeveling 6: maak duidelijk wat je data betekent

Wanneer je data openstelt voor derden, inclusief niet-specialisten, is het essentieel om eenduidig vast te leggen wat de data betekent, waarbij deze betekenis ook voor niet-specialisten begrijpelijk is. Het vastleggen van semantiek kan o.a. door definities en informatiemodellen goed te ontsluiten, maar ook door praktischere zaken als heldere naamgeving van variabelen etc.

3.4.7 Aanbeveling 7: wees vindbaar voor developers

Een goede, gebruiksgerichte API, die bovendien actief wordt beheerd en doorontwikkeld, kan nog steeds weinig gebruikt worden wanneer deze API niet goed vindbaar is. Zorg daarom dat je een goed developersportaal hebt, idealiter nationaal bij developer.overheid.nl. Presenteer breed toepasbare API’s en datasets daar prominenter dan specifiekere API’s en obscure datasets, wederom te vergelijken met de toptaken-aanpak bij gemeentelijke websites. Een goed developersportaal informeert niet alleen over beschikbare API’s, maar inspireert en verleidt zelfs developers om bepaalde API’s te gebruiken. Het vullen van het developersportaal mag daarom nooit sluitpost van een project zijn.

3.4.8 Aanbeveling 8: niet alles is een API!

Bedenkt altijd goed of een API de juiste oplossing is. In sommige gevallen is een bulk download nog steeds praktischer voor een gebruiker. Wanneer een API zinvol is? Hoe hoger de mutatiefrequentie van de data, hoe zinvoller een API wordt. En bij hoge mutatiefrequenties, is een API die was-wordt leveringen kan bieden zinvol.

4.2.1 Wat zijn resources?

Het fundamenteel concept in elke RESTful API is de resource. Een resource is een object met een type, bijbehorende data, relaties met andere resources en een aantal operaties om deze te bewerken. Resources worden aangeduid met zelfstandige naamwoorden (niet werkwoorden!) die relevant zijn vanuit het perspectief van de afnemer van de API. Dus resources zijn zelfstandige naamwoorden en operaties zijn werkwoorden. Operaties zijn acties die op resources worden uitgevoerd.

Het is mogelijk om interne datamodellen één-op-één toe te wijzen aan resources, maar dit hoeft niet per definitie zo te zijn. De crux is om alle niet relevante implementatiedetails te verbergen. Enkele voorbeelden van resources zijn: aanvraag, activiteit, pand, rijksmonument en vergunning.

Als de resources geïdentificeerd zijn, wordt bepaald welke operaties van toepassing zijn en hoe deze worden ondersteund door de API. RESTful API's realiseren CRUD (Create, Read, Update, Delete) operaties met behulp van HTTP-operaties:

Het mooie van REST is dat er gebruik wordt gemaakt van de bestaande HTTP operaties om de functionaliteit te implementeren met één enkel eindpunt. Hierdoor zijn er geen aanvullende naamgevingsconventies nodig in de URI en blijft de URIstructuur eenvoudig.

API principe: Alleen standaard HTTP-operaties worden toegepast

API principe: API-endpoints mogen géén trailing slashes bevatten

4.2.2 Welke taal?

Omdat de exacte betekenis van concepten en begrippen vaak in een vertaling verloren gaan, worden resources en de achterliggende entiteiten, velden, etc. in het Nederlands gedefinieerd.

API principe: Definitie van het koppelvlak is in het Nederlands tenzij er sprake is van een officieel Engelstalig begrippenkader

4.2.3 Naamgeving eindpunten in enkelvoud of meervoud?

De Keep It Simple Stupid (KISS) regel is hier van toepassing. Hoewel grammaticaal gezien het verkeerd aanvoelt om bij het opvragen van een enkele resource gebruik te maken van een resource naam in het meervoud, is het pragmatisch om te kiezen voor consistente eindpunten en altijd meervoud te gebruiken. Voor de afnemer is het gebruik veel eenvoudiger als er geen rekening gehouden hoeft te worden met enkel- en meervoud (aanvraag/aanvragen, regel/regels). Daarnaast is de implementatie eenvoudiger omdat de meeste ontwikkel frameworks het afhandelen van enkele resource (/aanvragen/12) en meervoudige resources (/aanvragen) met één controller kunnen oplossen.

API principe: Resource namen zijn zelfstandige naamwoorden in het meervoud

4.2.4 Hoe omgaan met relaties?

Als een relatie alleen kan bestaan binnen een andere resource (1-op-n relatie), dan kan de afhankelijke resource (kind) alleen via de ouder benaderd worden. Het volgende voorbeeld maakt dit duidelijk. Een status hoort bij één aanvraag. De statussen worden als volgt benaderd via het eindpunt /aanvragen:

API principe: Relaties van geneste resources worden binnen het eindpunt gecreëerd

Indien er sprake is van een n-op-n relatie zijn er verschillende manieren om de resources te benaderen. De onderstaande verzoeken leveren hetzelfde resultaat op:

Bij een n-op-m relatie wordt het opvragen van de individuele resources sowieso ondersteund, waarbij minimaal de identificatie van gerelateerde resources (relatie) wordt teruggegeven. De afnemers moet zelf het eindpunt van de gerelativeerde resource (relatie) aanroepen om deze op te vragen. Dit wordt ook wel aangeduid als lazy loading. De afnemer bepaalt zelf of de relatie geladen wordt en op welk moment.

De resource dient naast "lazy loading" (de standaard) ook "eager loading" te ondersteunen, zodat de afnemer kan aangeven dat relaties direct meegeladen moeten worden. Dit wordt gerealiseerd middels de standaard query-parameter expand=true. Dit voorkomt dat er twee of meer aparte aanroepen nodig zijn. In beide gevallen is de afnemer in control.

API principe: Resources ondersteunen bij voorkeur "lazy" en "eager" laden van relaties

4.2.5 Automatische laden van gelinkte resources

Vaak wordt er vanuit één resource verwezen (gelinkt) naar andere (geneste) resources. De RESTful manier om dit op te lossen is de verwijzing naar andere resources als URI op te nemen in een resource. Op basis hiervan kan de afnemer, indien gewenst, de gelinkte resources zelf opvragen. Dit is vergelijkbaar met "lazy loading" in een Object Relational Mapping (ORM) oplossing: resources worden alleen opgehaald als ze nodig zijn. In sommige gevallen, als de afnemer alle resources nodig heeft, is het efficiënter als de geneste resources in één keer opgehaald worden. Dit is vergelijkbaar met "eager loading" patroon in een ORM-oplossing.

Omdat dit tegen de REST principes in gaat, moet het toepassen van dit mechanisme een expliciete keuze zijn. De keuze wordt bij de afnemers van de API belegd, zij weten immers of ze extra informatie nodig hebben en welke informatie precies. Dit mechanisme wordt mogelijk gemaakt met de expand query-parameter.

Als expand=true wordt meegegeven, dan worden alle geneste resources geladen en embedded in het resultaat teruggegeven. Om de hoeveelheid informatie die geretourneerd wordt te beperken, is verplicht om te specificeren welke resources en zelfs welke velden van een resource teruggeven moeten worden. Hiermee wordt voorkomen dat de hele database wordt leeg getrokken.

Dit wordt gedaan door de resources als een komma's gescheiden lijst te specificeren, bijvoorbeeld: expand=aanvrager,bevoegdGezag. De dot-notatie wordt gebruikt om specifieke velden van resources te selecteren. In het onderstaande voorbeeld wordt van de aanvrager alleen het veld "naam" teruggeven en van het bevoegd gezag de complete resource. Conform de [HAL]-standaard zijn de gelinkte resources embedded in de standaard representatie (zie ook aanpasbare representatie).

GET /aanvragen/12?expand=aanvrager.naam,bevoegdGezag

Dit levert het volgende resultaat op:

{
"id": "12",
"naam": "Mijn dakkapel",
"samenvatting": "Ik wil een dakkapel bouwen!",
"_embedded": {
  "aanvrager": {
    "naam": "Bob",
    "_links": {
      "self": {
        "href": "https: //.../api/register/v1/aanvragers/847",
        "title": "Bob"
      }
    }
  },
  "bevoegdGezag": {
    "id": "42",
    "soort": "Gemeente",
    "naam": "Rotterdam",
    "_links": {
      "self": {
        "href": "https: //.../api/register/v1/bevoegde-gezagen/42",
        "title": "Rotterdam"
      }
    }
  }
},
"_links": {
  "self": {
    "href": "https: //.../api/register/v1/aanvragen/12",
    "title": "Mijn dakkapel"
  }
}
}

Afhankelijk van de implementatie zal door het selectief kunnen laden van gelinkte resources in veel gevallen de overhead van database selecties, hoeveelheid serialisatie en hoeveelheid uitgewisselde data worden beperkt.

API principe: Gelinkte resources worden expliciet en selectief mee-geladen

4.2.6 Aanpasbare representatie

De gebruiker van een API heeft niet altijd de volledige representatie (lees: alle velden) van een resource nodig. De mogelijkheid bieden om de gewenste velden te selecteren helpt bij het beperken van het netwerkverkeer (relevant voor lichtgewicht toepassingen), vereenvoudigt het gebruik van de API en maakt deze aanpasbaar (op maat). Om dit mogelijk te maken wordt de query-parameter fields ondersteund. De query-parameter accepteert een door komma's gescheiden lijst met veldnamen. Het resultaat is een representatie op maat. Het volgende verzoek haalt bijvoorbeeld voldoende informatie op om een gesorteerde lijst van open aanvragen te tonen.

In het geval van HAL zijn de gelinkte resources embedded in de standaard representatie. Met de hier beschreven fields parameter ontstaat de mogelijkheid om de inhoud van de body naar behoefte aan te passen.

GET /aanvragen?fields=id,onderwerp,aanvrager,wijzigDatum&status=open&sorteer=wijzigDatum

API principe: Indien representatie op maat wordt ondersteund, dan conform dit principe

4.2.7 Hoe om te gaan met acties die niet passen in het CRUD model?

Er zijn ook resource-acties die niet data manipulatie (CRUD) gerelateerd zijn. Een voorbeeld van dit soort acties zijn: het wijzigen van de status (activeren en deactiveren) van een resource of het markeren (star) van een resource. Afhankelijk van het type actie zijn er drie manieren om dit aan te pakken:

1. Herstructureer de actie zodat deze onderdeel wordt van een resource. Dit werkt als de actie geen parameters nodig heeft. Bijvoorbeeld een activeeractie kan worden toegewezen aan een booleaans veld geactiveerd dat bijgewerkt wordt via een PATCH op de resource.

2. Behandel de actie als een sub-resource. Bijvoorbeeld, een aanvraag markeren met PUT /aanvragen/12/markeringen en verwijderen van de markering met DELETE /aanvragen/12/markeringen. Om de REST principes volledig te volgen moet ook de GET methode voor deze sub-resource beschikbaar zijn.

3. Soms is er geen logische manier om een actie aan een bestaande resource te koppelen. Een voorbeeld hiervan is een zoekopdracht over meerdere resources heen. Deze actie kan niet worden toegekend aan een specifieke resource. In dit geval is de keuze voor een zelfstandig service-eindpunt /_zoek het meest logische. Gebruik werkwoorden in gebiedende wijs om het onderscheid t.o.v. "echte" resource endpoints zo duidelijk mogelijk te maken. Dit is vanuit het perspectief van de gebruiker het meest logisch ontwerp.

In de Nederlandse API-strategie wordt gekozen voor manier 2 en 3.

API principe: Acties die niet passen in het CRUD model worden een sub-resource

4.3.1 Authenticatie en autorisatie

Een REST API mag geen toestand (state) bijhouden. Dit betekent dat authenticatie en autorisatie van een verzoek niet mag afhangen van cookies of sessies. In plaats daarvan wordt elk verzoek voorzien van een token. Binnen het Kennisplatform APIs is gekozen voor OAuth 2.0 als de standaarden voor het autorisatiemechanisme waar dit nodig is. In hoofdstuk 5 is meer informatie te vinden over het gebruike van OAuth 2.0.

API principe: Tokens worden niet gebruikt in query parameters

Bij het gebruik van tokens wordt onderscheid gemaakt tussen geauthentiseerde en niet-geauthentiseerde services met de bijhorende headers:

Bij het ontbreken van de juiste headers zijn geen authenticatiedetails beschikbaar en dient de statuscode 403 Forbidden terug te worden gegeven.

API principe: Autorisatie is waar nodig gebaseerd op OAuth 2.0

Zie ook Het Nederlands profiel OAuth in het hoofdtuk beveiliging voor een nadere uitwerking van de toepassing van OAuth.

API principe: Authenticatie voor API's met toegangsbeperking of doelbinding is gebaseerd op PKIoverheid

4.4.1 Best practice(s)

API principe: OAS via basis-URI beschikbaar in JSON-formaat

4.5.1 Uitfaseren van een major API versie

Major releases van API's zijn altijd backward incompatible. Immers, als een nieuwe release van de API niet tot backward incompatibiliteit leidt, is er geen reden om een hele versie omhoog te gaan en spreken we van een minor release. Op het moment dat er een major release plaatsvindt, is het de bedoeling dat alle (potentiële) clients deze nieuwe versie implementeren.

Omdat we geen clients willen breken kunnen we niet van de een op de andere dag overschakelen van de oude naar de nieuwe versie, zoals dat bijvoorbeeld bij een update van een website wel vaak gebeurt. Daarom is het noodzakelijk om na de livegang van de nieuwe versie óók de oude versie in de lucht te houden. Omdat we de oude versie niet tot in de eeuwigheid willen blijven onderhouden en juist iedereen willen stimuleren om de nieuwe versie te gaan gebruiken, communiceren we een periode waarin clients de gelegenheid krijgen om hun code aan te passen aan de nieuwe versie. Deze periode noemen we de deprecation periode. De lengte van deze periode kan verschillen per API, vaak is dit zes maanden, maar niet meer dan één jaar. Met het oog op beheersbaarheid is het ten zeerste aan te bevelen om maximaal twee major versies (waarvan één de deprecated variant) naast elkaar te draaien. In deze fase is communicatie met clients van de oude versie cruciaal. De volgende zaken moeten gecommuniceerd worden:

• Een link naar de (documentatie van de) nieuwe versie van de API;
• Deprecation periode met exacte datum waarop de deprecated versie offline wordt gehaald;
• Migratieplan om eenvoudig over te stappen naar de nieuwe versie;
• Welke features er toegevoegd, gewijzigd of verwijderd worden;
• Welke wijzigingen de huidige implementaties kunnen breken;
• Contactmogelijkheid om een verlenging van de deprecation periode aan te vragen.

Deze zaken dienen gecommuniceerd te worden via de volgende kanalen:

• Per e-mail van de clients (indien bekend);
• Duidelijk leesbaar in de API documentatie van de oude versie;
• Met een Warning response header in alle responses van de oude API.

Stap voor stap betekent dit het volgende:

1. Lanceren nieuwe versie;
2. Bepalen deprecation periode;
3. Schrijven migratieplan;
4. Communiceren in de API-documentatie van de oude versie;
5. Deprecation periode communiceren per e-mail, forum en eventuele andere kanalen;
6. Warning header toevoegen aan responses van de oude versie;
7. Logs checken om gebruik van de oude versie te monitoren gedurende deprecation periode;
8. End-point oude versie dichtzetten op geplande datum en feedback monitoren;
9. Indien er binnen twee weken geen feedback op de oude versie komt kan de oude versie (inclusief docs) verwijderd worden;

4.5.2 De Warning response header

De Warning header (zie: RFC 7234) die we hier gebruiken heeft warn-code 299 ("Miscellaneous Persistent Warning") en het API endpoint (inclusief versienummer) als de warn-agent van de warning, gevolgd door de warn-text met de human-readable waarschuwing. Voorbeeld:

Waarschuwing: 299 https://service.../api/.../v1 "Deze versie van de API is verouderd en zal uit dienst worden genomen op 2018-02-01. Raadpleeg voor meer informatie hier de documentatie: https://omgevingswet.../api/.../v1".

Gebruikers moeten voldoende tijd hebben om de oude API uit te faseren. Een periode van 6 tot 12 maanden wordt aanbevolen.

API principe: Gebruikers van een 'deprecated' API worden actief gewaarschuwd

4.6.1 Veldnamen in snake_case, camelCase, UpperCamelCase of kebab-case?

Bij veldnamen wordt gebruik gemaakt van camelCase.

API principe: Woorden in veldnamen zijn gedefinieerd in camelCase

4.6.2 Pretty print

De meeste REST clients en browsers (al dan niet met extensies) kunnen JSON netjes geformatteerd weergeven, ook als de response geen white-space bevat.

API principe: Pretty print is standaard uitgeschakeld

4.6.3 Gebruik geen envelop

Veel API's wikkelen antwoorden in enveloppen zoals hieronder is weergegeven:

{
"persoon": {
  "naam": "Jan",
  "geboortejaar": 1983
}
}

Een toekomstbestendig API is vrij van enveloppen.

API principe: Een JSON-response heeft geen omhullende envelop

4.6.4 JSON gecodeerde POST, PUT en PATCH payloads

API's ondersteunen minimaal JSON gecodeerde POST, PUT en PATCH payloads. Encoded form data (application/x-www-form-urlencoded) payloads worden niet ondersteund. Wat is het verschil?

Content-Type: application/json resulteert in:

{
"Name": "John Smith",
"Age": 23
}

en Content-Type: application/x-www-form-urlencoded resulteert in: Name=John+Smith&Age=23

API principe: API's ondersteunen JSON gecodeerde POST, PUT en PATCH payloads

4.7.1 Filteren

Om te filteren wordt gebruik gemaakt van unieke query-parameters die gelijk zijn aan de velden waarop gefilterd kan worden. Als je bijvoorbeeld een lijst met aanvragen wilt opvragen van het eindpunt /aanvragen en deze wilt beperken tot open aanvragen, dan wordt het verzoek GET /aanvragen?status=open gebruikt. Hier is status een veld waarop gefilterd kan worden.

API principe: Filter query-parameters zijn gelijk aan de velden waarop gefilterd kan worden

Dezelfde systematiek kan worden gehanteerd voor geneste properties. Zoals uitgewerkt met een voorbeeld op basis van de volgende collectie:

[{
"id": 1,
"status": "actief",
"overheid": {
  "code": "0000",
  "naam": "Ministerie van BZK"
}
}, {
"id": 2,
"status": "inactief",
"overheid": {
  "code": "9901",
  "naam": "Provincie Gelderland"
}
}]

Alle objecten met de status "actief" kunnen worden gefilterd met /?status=actief. Maar als daarnaast ook op objecten met code "0000" van de overheid gefilterd moeten worden, heeft dit betrekking op een geneste property. Hier kan dan de puntnotatie (zoals bij Javascript) voor worden gebruikt: /?status=actief&overheid.code=0000.

4.7.2 Sorteren

Voor sorteren wordt de query-parameter sorteer gebruikt. Deze query-parameter accepteert een lijst van velden waarop gesorteerd moet worden gescheiden door een komma. Door een minteken ("-") voor de veldnaam te zetten wordt het veld in aflopende sorteervolgorde gesorteerd. Een aantal voorbeelden:

API principe: Voor sorteren wordt de query-parameter sorteer gebruikt

4.7.3 Zoeken

Soms zijn eenvoudige filters onvoldoende en is de kracht van vrije-tekst zoekmachines nodig. API's ondersteunen dit middels de query-parameter zoek. Het resultaat wordt in dezelfde representatie teruggegeven.

API principe: Voor vrije-tekst zoeken wordt een query-parameter zoek gebruikt

Voorbeelden van de combinatie filteren, sorteren en zoeken:

4.7.4 Wildcards

API's die vrije-tekst zoeken ondersteunen kunnen overweg met twee soorten wildcard karakters:

• * Komt overeen met nul of meer (niet-spatie) karakters
• ? Komt precies overeen met één (niet-spatie) karakter

Bijvoorbeeld, he* zal overeenkomen met elk woord dat begint met he, zoals hek, hemelwaterafvoer, enzovoort. In het geval van he? komt dit alleen overeen met drie letterwoorden die beginnen met he, zoals hek, heg, enzovoort.

API principe: API's die vrije-tekst zoeken ondersteunen kunnen overweg met twee soorten wildcard karakters: * en ?

Hieronder volgen nog een aantal basisregels voor wildcards in zoekopdrachten:

• Er kan meer dan één wildcard in één zoekterm of zin voorkomen.
• De twee wildcard karakters kunnen in combinatie worden gebruikt. Bijvoorbeeld m*?? komt overeen met woorden die beginnen met m en drie of meer tekens hebben.
• Spaties (URL-encoded als %20) worden gebruikt als woordscheiding en wildcardmatching werkt alleen binnen een enkel woord. Bijvoorbeeld, r*te* komt overeen met de ruimtelijk, maar niet met ruimte tekort.
• Wildcards werken alleen op JSON-velden met tekst (string) waarden.

4.7.5 Aliassen voor terugkerende queries

Om de API ervaring verder te verbeteren is het mogelijk om terugkerende queries als endpoints aan te bieden. Zo kunnen onlangs gesloten aanvragen als volgt worden benaderd:

GET /aanvragen/recent-gesloten

4.8.1 Mate van ondersteuning

Tijdreizen is een optioneel mechanisme met optionele features. Het kan dus voorkomen dat:

• tijdreizen in het geheel niet wordt ondersteund;
• het begrip inwerkingtreding niet wordt ondersteund;
• tijdreizen naar de toekomst niet wordt ondersteund.

Bij de verwerking van tijdreisvragen dient de afnemer geïnformeerd te worden over ongeldige/niet ondersteunde verzoeken. In de volgende specifieke gevallen wordt de bijbehorende statuscode en toelichting teruggegeven:

4.8.2 Robuustheid

Bij de verwerking van tijdreisvragen dient ook rekening te worden gehouden met het ontbreken van historie en globale vragen in een resource-collectie. In volgende specifieke gevallen wordt de bijbehorende statuscode en toelichting teruggegeven:

4.9.1 Resultaat (response)

In een JSON API wordt een geometrie teruggegeven als GeoJSON. We kiezen er voor om dit binnen de application/json te ‘wrappen' in een apart GeoJSON object.

API principe: GeoJSON is onderdeel van de embedded resource in de JSON response

4.9.2 Aanroep (requests)

Een geografisch filter kan erg complex en groot zijn. Het is daarom een best practice om dergelijke complexe vragen niet in de request URI, maar in de body mee te sturen. Omdat GET geen payload mag hebben (hoewel sommige clients dit wel ondersteunen) moet hier dus een andere methode voor gebruikt worden.

In analogie met API's zoals die van Elasticsearch, is een POST naar een apart endpoint de juiste weg om te bewandelen. Het onderstaande voorbeeld doet een zogenaamde GEO-query naar alle panden waarin het veld _geo (er kunnen ook andere velden zijn, zoals hoofdgeometrie, binnenOmtrek, buitenOmtrek, etc.) het GeoJSON object (in dit geval een Point, dus één coördinaat) bevat:

// POST /api/v1/panden/_zoek met request body:
{
"_geo": {
  "contains": {
    "type": "Point",
    "coordinates": [5.9623762, 52.2118093]
  }
}
}

API principe: Voor GEO queries is een POST endpoint beschikbaar

Omdat we ons met het geo endpoint beperken tot een GEO-query en we wellicht ook gecombineerde queries willen doen is het sterk aan te bevelen om een generiek query endpoint in te richten:

// POST /api/v1/panden/_zoek met request body:
{
"_geo": {
  "contains": {
    "type": "Point",
    "coordinates": [5.9623762, 52.2118093]
  }
},
"status": "Actief"
}

API principe: POST endpoints zijn uitbreidbaar voor gecombineerde vragen

Naast contains kan er ook intersects (snijdt) of within (valt binnen) als operators gebruikt worden. De benamingen van deze operators komen uit de GEO-wereld en die willen we niet opnieuw uitvinden. Zie voor meer details: https://www.w3.org/TR/sdw-bp/#entity-level-links

Omdat we voor de geometrie een GeoJSON object gebruiken hoeven we hier geen syntax meer voor te verzinnen.

API principe: Resultaten van een globale zoekvraag worden in de relevante context geplaatst

In het volgende voorbeeld wordt aangegeven hoe dit kan worden gerealiseerd:

// POST /api/v1/_zoek:
{
"_embedded": {
  "results": [{
    "type": "enkelbestemming",
    "_links": {
      "self": {
        "title": "Enkelbestemming 1234",
        "href": "/enkelbestemmingen/1234"
      }
    }
  }, {
    "type": "dubbelbestemming",
    "_links": {
      "self": {
        "title": "Dubbelbestemming 8765",
        "href": "/dubbelbestemmingen/8765"
      }
    }
  }]
}
}

4.9.3 CRS-negotiation

Het default CRS (Coordinate Reference System) van GeoJSON is WGS84. Dit is het globale coördinatenstelsel dat overal ter wereld redelijk goed bruikbaar is, maar vanwege het gebruikte model van de aarde en de verschuiving van de tektonische platen minder nauwkeurig is dan lokale coördinatenstelsels zoals ETRS89 (EPSG:4258, Europees) of RD (EPSG:28992, Nederlands).

Omdat de meeste client-bibliotheken met WGS84 werken, schrijft de W3C/OGC werkgroep "Spatial Data on the Web" voor om dit standaard te ontsluiten. Dit kan direct op een kaart geplot worden zonder moeilijke transformaties. De API-strategie voorziet hierin door naast ETRS89 en RD ook WGS84 of Web Mercator (EPSG:3857, voor rasterdata) te ondersteunen.

API principe: Het voorkeur-coördinatenstelsels (CRS) is ETRS89, maar het CRS wordt niet impliciet geselecteerd

Het is mogelijk om het CRS voor vraag en antwoord via headers afzonderlijk te specificeren. Hierin zijn vervolgens drie opties (met voorgeschreven projecties) voorhanden: RD, ETRS89 en WGS84.

Een nadere opsomming van de uitgangspunten voor het CRS:

• Leg als bronsysteem binnenkomende formaat vast (juridische context);
• Coördinatenstelsels API-strategie: vraag/antwoord in RD; ETRS89; WGS84;
• Overweeg no-regret: vastleggen in ETRS89 én RD i.p.v. realtime bepalen;
• Hanteer RDNAPTRANS™ 2018 bij transformatie RD versus ETRS89 (correctiegrid);
• Presentatie afhankelijk van context (o.a. gebruikerswensen);
• Uitwisselingsformaat (notatie) ETRS89 en WGS84 X Y in decimale graden: DD.ddddddddd (voorbeeld: 52.255023450)
• Uitwisselingsformaat (notatie) RD X Y in meters (niet afgerond): 195427.5200 311611.8400

API principe: Het coördinatenstelsel (CRS) van de vraag en het antwoord wordt in de header meegestuurd

De hier genoemde headers zijn puur bedoeld voor de onderhandeling tussen de client en de server. Afhankelijk van de toepassing zal naast de geometrieën ook specifieke metadata onderdeel vormen van het antwoord, bijvoorbeeld de oorspronkelijke realisatie inclusief een inwindatum.

Vraag en antwoord kunnen op een ander coördinatensysteem zijn gebaseerd. Hiervoor wordt het HTTP-mechanisme voor content negotiation gebruikt. Het CRS van de geometrie in de vraag (request body) wordt aangeduid met de header Content-Crs.

Het gewenste CRS voor de geometrie in het antwoord (response body) wordt aangeduid met de header Accept-Crs.

4.9.4 CRS-transformatie

Voor het transformeren tussen coördinaatreferentiesystemen is binnen de Rijksoverheid software met een keurmerk beschikbaar.

API principe: Het gewenste coördinatenstelsel wordt op basis van content negotiation overeengekomen

4.11.1 ETag

Een ETag (Entity Tag) is een hashcode of checksum van een resource. Als de resource wijzigt ontstaat een andere ETag. Een ETag is dus uniek voor een bepaalde versie van een resource. De ETag wordt als de HTTP header ETag teruggegeven met de resource. De afnemer cached de resource en de ETag. Als de afnemer dezelfde resource opvraagt dan stuurt deze de ETag mee in de HTTP header If-None-Match. De server controleert of de ETag in de HTTP header If-None-Match gelijk is aan de eigen ETag. Indien dit het geval geeft de server een HTTP statuscode 304 Not Modified terug. De afnemer laadt dan de resource uit de eigen cache. Dit gaat alleen op over clientside caching, dus is alleen van toepassing als de client ook daadwerkelijk de request headers meestuurt, anders altijd een 200 OK.

4.11.2 Last-Modified

Dit werkt in principe net als ETag, behalve dat het gebruik maakt van tijdstempels. De HTTP header Last-Modified bevat een tijdstempel in het RFC 1123 formaat die wordt gevalideerd tegen de HTTP header If-Modified-Since. De server controleert of de resource gewijzigd is sinds het aangegeven tijdstip. Indien dit niet het geval is dan geeft de server een HTTP statuscode 304 Not Modified terug. De afnemer laadt dan de resource uit de eigen cache. Dit gaat alleen op over client-side caching, dus is alleen van toepassing als de client ook daadwerkelijk de request headers meestuurt, anders altijd een 200 OK.

API principe: Waar relevant wordt caching toegepast

4.13.1 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.

API principe: API's passen de verplichte HTTP statuscodes toe

Samenvatting HTTP-operaties in combinatie met de primaire HTTP statuscodes:

Hieronder een korte lijst met een beschrijving van de HTTP statuscodes die minimaal worden toegepast:

5.1.1 Expert advies OAuth forum standaardisatie

Het opstellen van deze standaard is voortgekomen uit het Expert advies OAuth [Expert]. Daarin wordt aangeraden eerst een nederlands profiel op stellen alvorens OAuth op de pas toe of leg uit lijst van het forum standaardisatie te plaatsen.

5.1.2 Werkingsgebied standaard

Als organisatorisch werkingsgebied wordt geadviseerd: Nederlandse overheden (Rijk, provincies, gemeenten en waterschappen) en instellingen uit de (semi-) publieke sector

5.1.3 Toepassingsgebied standaard

Als functioneel toepassingsgebied wordt voorgesteld: Het gebruik van OAuth 2.0 is verplicht voor applicaties waarbij gebruikers (resource owner) toestemming geven (impliciet of expliciet) aan een dienst (van een derde) om namens hem toegang te krijgen tot specifieke gegevens via een RESTful API. Het gaat dan om een RESTful API waar de resource owner recht tot toegang heeft.

5.1.4 OpenID connect buiten scope

de expertgroep is op 7 juli en op 22 september 2016 bijeengekomen om de standaarden, de aandachtspunten en openstaande vragen uit het voorbereidingsdossier te bespreken. Daarbij is vastgesteld dat OpenID Connect niet voor opneming op de lijst open standaarden in aanmerking komt.

5.1.5 Aansluiting op internationale standaard iGov

Het Nederlands profiel OAuth baseren we het internationale iGOV OAuth 2.0 profiel [iGOV.OAuth2] we nemen niet alle keuzes van dit internationale profiel over aangezien dit een aantal keuzes bevat die sterk leunen op de amerikaanse situatie. Het kan het best beschouwd worden als een fork waar we in ons profiel aangeven waar we afwijken. iGov heeft twee naast het OAuth profiel ook een OpenID connect profiel [iGOV.OpenID] wanneer mogelijk ook OpenID connect op de pas toe of leg uit lijst van het Forum standaardisatie komt kan dit Nederlandse profiel uitgebreid worden met een Nederlandse variant van het iGov OpenID Connect profiel. De usecase die hieronder wordt beschreven sorteerd daar al op voor.

Het Nederlands profiel OAuth is hier te vinden: https://geonovum.github.io/KP-APIs-OAuthNL/#dutch-government-assurance-profile-for-oauth-2-0

6.1.1 API-01: API's garanderen dat operaties "Veilig" en/of "Idempotent" zijn

Operaties van een API zijn gegarandeerd "Veilig" en/of "Idempotent" als dat zo is bepaald.

6.1.2 API-02: Toestandsinformatie wordt nooit op de server opgeslagen

De client-toestand wordt volledig bijgehouden door de client zelf.

6.1.3 API-03: Alleen standaard HTTP-operaties worden toegepast

Een RESTful API is een application programming interface die de standaard HTTP-operaties GET, PUT, POST, PATCH en DELETE gebruikt.

6.1.4 API-04: Definitie van het koppelvlak is in het Nederlands tenzij er sprake is van een officieel Engelstalig begrippenkader

Resources en de achterliggende entiteiten, velden, etc. (het informatiemodel en het externe koppelvlak) worden in het Nederlands gedefinieerd. Engels is toegestaan indien er sprake is van een officieel Engelstalig begrippenkader.

6.1.5 API-05: Resource namen zijn zelfstandige naamwoorden in het meervoud

Namen van resources zijn zelfstandige naamwoorden en altijd in het meervoud, zoals aanvragen, activiteiten, vergunningen. Ook als het om het een enkel resource betreft.

6.1.6 API-06: Relaties van geneste resources worden bij voorkeur binnen het eindpunt gecreëerd

Als een relatie alleen kan bestaan binnen een andere resource (geneste resource), wordt de relatie bij voorkeur innen het eindpunt gecreëerd. De afhankelijke resource heeft in dat geval geen eigen eindpunt

6.1.7 API-07: Resources ondersteunen bij voorkeur "lazy" en "eager" laden van relaties

Resources die een n-op-n relatie kennen ondersteunen bij voorkeur zowel het teruggeven van identificaties van gerelateerde resources (lazy loading) als het teruggeven van de resources zelf (eager loading).

6.1.8 API-08: Gelinkte resources worden expliciet en selectief mee-geladen

Gelinkte resources worden expliciet en selectief mee-geladen als onderdeel van een resource verzoek middels de expand query-parameter.

6.1.9 API-09: Indien representatie op maat wordt ondersteund, dan conform dit principe.

Het is mogelijk om een door komma's gescheiden lijst van veldennamen op te geven met de query-parameter fields om een representatie op maat te krijgen. Als niet-bestaande veldnamen worden meegegeven wordt een 400 Bad Request teruggegeven.

6.1.10 API-10: Acties die niet passen in het CRUD model worden een sub-resource

"Acties die niet passen in het CRUD model worden op de volgende manieren opgelost:

• Behandel een actie als een sub-resource.

• Alleen in uitzonderlijke gevallen wordt een actie met een eigen eindpunt opgelost."

6.1.11 API-11: De verbinding is ALTIJD versleuteld met minimaal TLS V1.2

De verbinding is ALTIJD versleuteld op basis van minimaal TLS V1.2. Geen uitzonderingen, dus overal en altijd. In het geval van toegangsbeperking of doelbinding wordt tweezijdig TLS toegepast. Doordat de verbinding altijd is versleuteld maakt het authenticatiemechanisme eenvoudiger. Hierdoor wordt het mogelijk om eenvoudige toegangstokens te gebruiken in plaats van toegangstokens met encryptie.

6.1.12 API-12: API's zijn bij voorkeur alleen bruikbaar met behulp van een API-key

Voor alle API's wordt bij voorkeur minimaal een registratie inclusief acceptatie van de fair use voorwaarden vereist. Op basis hiervan zal dan een API-key wordt uitgegeven.

6.1.13 API-13: Tokens worden niet gebruikt in query parameters

Er is een inherent beveiligingsprobleem bij het gebruik van een query parameter voor tokens omdat de meeste webservers queryparameters in de server logs wegschrijven.

6.1.14 API-14: Autorisatie is waar nodig gebaseerd op OAuth 2.0

Een REST API mag geen state hebben. Elk verzoek moet daarom zijn voorzien van een token. OAuth 2.0 is hiervoor de voorgeschreven standaard, hoofstuk Beveiliging bevat meer informatie.

6.1.15 API-15: Authenticatie voor API's met toegangsbeperking of doelbinding is gebaseerd op PKIoverheid

In het geval van API's met toegangsbeperking of doelbinding zal er aanvullend sprake zijn van authenticatie op basis PKIoverheid certificaten en tweezijdig TLS.

6.1.16 API-16: Documentatie is gebaseerd op OAS 3.0 of hoger

Specificaties (documentatie) is beschikbaar als Open API Specification (OAS) V3.0 of hoger.

6.1.17 API-17: Documentatie is in het Nederlands tenzij er sprake is van bestaande documentatie in het Engels of er sprake is van een officieel Engelstalig begrippenkader

De voertaal voor de API's is Nederlands. Het is wel toegestaan om te verwijzen naar bestaande documentatie is het Engels en als er sprake is van een officieel Engelstalig begrippenkader.

6.1.18 API-18: Wijzigingen worden gepubliceerd met een uitfaseringschema

Koppelvlak wijzigingen worden met bijbehorende planning op een publiek toegankelijke blog als changelog bekendgemaakt en via een mailinglijst.

6.1.19 API-19: De overgangsperiode bij een nieuwe API versie is maximaal 1 jaar

Oude en nieuwe versies (max. 3) van een API worden voor een beperkte overgangsperiode (1 jaar) naast elkaar aangeboden.

6.1.20 API-20: Alleen het major versienummer is onderdeel van de URI

In de URI wordt alleen het major versienummer opgenomen. Minor versienummer en patch versienummer worden in de header van het bericht zelf opgenomen. Het uitgangspunt dat hierbij wordt gehanteerd is dat minor versies en patches geen impact hebben op bestaande code, maar major versies wel.

6.1.21 API-21 Gebruikers van een ‘deprecated' API worden actief gewaarschuwd

Met een Warning response-header in alle responses van de oude API's worden gebruikers gewaarschuwd voor de aanstaande uitfasering.

6.1.22 API-22: JSON first - API's ontvangen en versturen JSON

API's ontvangen en versturen JSON.

6.1.23 API-23: API's zijn optioneel voorzien van een JSON Schema

API's ondersteunen JSON Schema (<http: json-schema.org),="">zodat validatie mogelijk (optioneel) is en vereenvoudigd wordt.

6.1.24 API-24: Content negotiation wordt volledig ondersteund

Andere representaties zoals XML en RDF worden naast JSON via het standaard HTTP content negotiation mechanisme ondersteund. Als het gewenste formaat niet geleverd kan worden zal er een 406 Not Acceptable worden teruggegeven.

6.1.25 API-25: API's controleren dat de Content-Type header is ingesteld

Er wordt gecontroleerd of het Content-Type header is ingesteld op application/json of andere ondersteunde content types, anders wordt HTTP statuscode 415 Unsupported Media Type geretourneerd.

6.1.26 API-26: Woorden in veldnamen zijn gedefinieerd in camelCase

Een veldnaam begint met kleine letters (eerste woord) en ieder opvolgend woord begint met een hoofdletter.

6.1.27 API-27: Pretty print is standaard uitgeschakeld

Het uitgangspunt is dat REST clients en browsers (al dan niet met extensies) JSON netjes geformatteerd kunnen weergeven.

6.1.28 API-28: Een JSON-response heeft geen omhullende envelop

Er worden standaard geen enveloppen toegepast.

6.1.29 API-29: API's ondersteunen JSON gecodeerde POST, PUT en PATCH payloads

API's ondersteunen minimaal JSON gecodeerde POST, PUT en PATCH payloads. Encoded form data (application/x-www-form-urlencoded) wordt niet ondersteund.

6.1.30 API-30: Filter query-parameters zijn gelijk aan de velden waarop gefilterd kan worden

Gebruik unieke query-parameters die gelijk zijn aan de velden waarop gefilterd kan worden.

6.1.31 API-31: Voor sorteren wordt de query-parameter sorteer gebruikt

De generieke query-parameter sorteer wordt gebruikt voor het specificeren van door komma's gescheiden velden waarop gesorteerd moet worden. Door een minteken (-) voor de veldnaam te zetten wordt het veld in aflopende sorteervolgorde gesorteerd.

6.1.32 API-32: Voor vrije-tekst zoeken wordt een query-parameter zoek gebruikt

API's die vrije-tekst zoeken ondersteunen doen dit middels de query-parameter zoek.

6.1.33 API-33: API's die vrije-tekst zoeken ondersteunen kunnen overweg met twee soorten wildcard karakters: * en ?

API's die vrije-tekst zoeken ondersteunen kunnen overweg met twee soorten wildcard karakters:

• * Komt overeen met nul of meer (niet-spatie) karakters

• ? Komt precies overeen met één (niet-spatie) karakter

6.1.34 API-34: GEO API's ontvangen en versturen bij voorkeur GeoJSON

Voor GEO API's wordt bij voorkeur de standaard GeoJSON (RFC-7946) gebruikt.

6.1.35 API-35: GeoJSON is onderdeel van de embedded resource in de JSON response

Als een JSON (application/json) response een geometrie bevat, dan wordt deze geometrie op dezelfde manier teruggegeven als het geometry object van GeoJSON (RFC-7946):

{
 "type": "Point",
 "coordinates": [125.6, 10.1]
}

6.1.36 API-36: Voor GEO queries is een POST end-point beschikbaar

Geometrische queries worden in een POST naar een apart endpoint verzonden.

6.1.37 API-37: POST end-points zijn uitbreidbaar voor gecombineerde vragen

De geometrie is uitbreidbaar met andere properties voor gecombineerde queries.

6.1.38 API-38: Resultaten van een globale geometrische zoekvraag worden in de relevante geometrische context geplaatst

In het geval van een globale zoekvraag /api/v1/_zoek is het noodzakelijk om de resultaten in een relevante context te plaatsen, omdat resultaten van verschillende collecties door elkaar teruggegeven worden. Met de property type kan in enkelvoud de naam van de collectie waar het resultaat toe behoort uitgedrukt worden.

6.1.39 API-39: Het voorkeur-coördinatenstelsels (CRS) is ETRS89, maar het CRS wordt niet impliciet geselecteerd

Algemeen gebruik van het Europese ETRS89 coördinatenstelsel (CRS) heeft sterk de voorkeur, maar dit wordt niet door API's afgedwongen als de "default". Derhalve moet het te gebruiken CRS in elke aanroep expliciet worden opgegeven.

6.1.40 API-40: Het coördinatenstelsel (CRS) van de vraag en het antwoord wordt in de header meegestuurd

Het gekozen coördinatenstelsel (CRS) voor zowel de vraag als het antwoord worden meegestuurd als onderdeel van de request-header en de response-header. Bij het ontbreken van deze headers wordt 412 Precondition Failed teruggegeven. Hiermee wordt voorkomen dat per abuis met het verkeerde CRS wordt gewerkt

6.1.41 API-41: Het gewenste coördinatenstelsel wordt op basis van content negotiation overeengekomen

Het gewenste CRS voor de geometrie in het antwoord (response body) wordt aangeduid met een Accept-Crs header. Als het gewenste CRS niet geleverd kan worden zal er een 406 Not Acceptable worden teruggegeven.

6.1.42 API-42: Paginering wordt gerealiseerd op basis van JSON+HAL bij media type: application/hal+json

Aan de representatie worden twee gereserveerde velden _links (verplicht) en _embedded (optioneel) toegevoegd. Daarnaast wordt paginerings-metadata als HTTP headers meegegeven.

6.1.43 API-43: Waar relevant wordt caching toegepast

Voor caching wordt gebruikt van de HTTP standaard caching mechanismes door het toevoegen van een aantal extra uitgaande HTTP headers (ETag of Last-Modified) en functionaliteit om te bepalen of een aantal specifieke inkomende HTTP headers (If-None-Match of If-Modified-Since).

6.1.44 API-44: Beperken van het aantal verzoeken per tijdsperiode wordt aangeraden

Aangeraden worden om het aantal verzoeken per tijdsperiode te beperken om overbelasting van servers te voorkomen om een hoog serviceniveau te garanderen.

6.1.45 API-45: Begrenzingen worden proactief gemeld

Gebruik X-Rate-Limit headers om limieten aan de gebruiker te communiceren en HTTP statuscode 429 Too Many Requests als de limieten overschreden worden.

6.1.46 API-46: Foutafhandeling is gestandaardiseerd

API's ondersteunen de gestandaardiseerde foutmeldingen van de HTTP-statuscodes 400 en 500 reeks inclusief een verwerkbare JSON representatie in lijn met RFC7807.

6.1.47 API-47: API's passen de verplichte HTTP-statuscodes toe

De volgende http-statuscodes worden minimaal toegepast: 200, 201, 204, 304, 400, 401, 403, 405, 406, 409, 410, 415, 422, 429, 500, 503.

6.1.48 API-48: API-endpoints mogen géén trailing slashes bevatten

URIs die gebruikt worden om collecties van resources of individuele resources op te vragen eindigen nooit met een trailing slash. Een resource leeft op één plek/path. Resource paths eindigen zonder slash.

6.1.49 API-49: Gebruik "publieke" API-Key

In JavaScript dient alleen gebruik te worden gemaakt van een zogenaamde "restricted" API-key. Dit is API-key die gekoppeld is aan specifieke kenmerken van de aanroeper (web-app, mobile-app), waaronder een clientId en/of verwijzer-URL.

6.1.50 API-50: Controleer toegang en gebruik CORS-header

Controleer eerst het domein van de inkomende aanvraag en genereer de response-header afhankelijk van of dit domein verzoeken mag verzenden of niet (whitelist). In dat geval wordt alleen dit specifieke domein aan de response-header Access-Control-Allow-Origin toegevoegd.

**LET OP: Het is technisch mogelijk om in de Access-Control-Allow-Origin responsheader een wildcard ("*") terug geven en zo alle bronnen toe te staan. Dit is een onveilige praktijk!**

6.1.51 API-51: OAS via basis-URI beschikbaar in JSON-formaat

Om te zorgen dat de actuele documentatie altijd publiekelijk toegankelijk is, is het advies om de inhoud van de Open API Specification op het "root endpoint" van de API beschikbaar te maken in JSON-formaat:

https://service.omgevingswet.overheid.nl/publiek/catalogus/api/raadplegen/v1

Maakt de OAS behorend bij v1 van deze API beschikbaar.

Hiermee wordt een unieke plek (die altijd synchroon loopt met de features die de API biedt) gekoppeld aan de actuele documentatie.

6.2.1 Inleiding

Doel van dit hoofdstuk is om een hoog niveau overzicht te geven van relevante onderdelen en concepten en hun samenhang in een op (REST) API gebaseerde architectuur waarbij gebruik gemaakt wordt van (REST) API's als interface voor de aangeboden (gegevens)diensten. Specifiek voor REST API's is dat deze 'Resource' gericht zijn en een uniforme manier bieden om resources te lezen, wijzigen, toevoegen of verwijderen.

Figuur 1: De plaats van API's bij aanbod en gebruik van (gegevens)diensten;

Figuur 1 toont de plaats van API's in de gegevensuitwisseling en relevante onderwerpen in deze context. Bij de Dienst afnemer speelt het gebruik van API's, bij de Dienst aanbieder speelt het aanbieden van API's.

In dit hoofdstuk wordt specifiek ingegaan op de 'aanbod kant': het onderdeel 'Diensten toegang' in het schema.

6.2.2 Diensten toegang & API management

Een diensten aanbieder ontsluit zijn diensten middels API's aan een diensten afnemer; om deze API's gecontroleerd aan te bieden is management en beheer van de API's van de organisatie noodzakelijk.

Een organisatie heeft verschillende soorten API's:

Open API's: voor ontsluiten van diensten zonder toegangsbeperking bv open data.

Gesloten API's: voor ontsluiten van diensten met toegangsbeperking bv persoonsgegevens en vertrouwelijke gegevens of diensten voor specifieke partijen.

Figuur 2 beschrijft vanuit het perspectief van een overheidsorganisatie als dienstaanbieder de onderwerpen die aandacht vragen in een op API's gebaseerde architectuur. Hieronder worden deze onderwerpen uitgebreider toegelicht.

Figuur 2: Onderdelen van een API architectuur - Algemeen overzicht

API-Gateway

Dit is het runtime onderdeel dat op de organisatiegrens van de diensten aanbieder de API-aanroepen ontvangt.

Throttling
Het beschermen van de dienst tegen overbelasting door de hoeveelheid aanvragen te beperken. Een aandachtspunt hierbij is de SLA afspraak die mogelijk hierbij van toepassing is en dat kritische bedrijfsprocessen de vereiste beschikbaarheid verkrijgen of behouden;

Authenticatie
Het vaststellen van de identiteit van de afnemer van de API;
(Zie ook : https://www.noraonline.nl/wiki/Identity_%26_Access_Management)

Autorisatie
Het bepalen of de afnemer recht heeft tot gebruik van de API;

Routering
Dit betreft het routeren van de API-aanroep naar de juiste achterliggende applicatie;

Logging
Dit betreft het loggen van API aanroepen van diensten afnemers;

API Management

Dit onderdeel betreft het beheren van de API's van de dienstenaanbieders. Op basis van de registratie van API's kan de life-cycle van de API beheerd worden, de runtime omgeving worden ingericht en partners en developers worden voorzien van informatie over het gebruik van de API's;

Toegang De dienstaanbieder administreert wie toegang heeft tot welke API. De runtime omgeving (API-gateway) wordt geconfigureerd volgens de gewenste toegangsregels om de toegang te bewaken;

API Meta Data De dienstaanbieder administreert welke API's door de onderneming aangeboden worden. Dit betreft zowel open API's als gesloten API's;

API Life Cycle De dienstaanbieder beheert de levenscyclus van de API's (design, test, productie, afvoer);

Monitoring De dienstaanbieder monitort beschikbaarheid en gebruik van de API's;

Developer Portal

Het Developer portal ondersteunt de ontwikkelaar bij het gebruik van API's. Bijvoorbeeld door middel van documentatie, voorbeelden, API-register (overzicht van alle beschikbare API's), sandbox voor experimenten en ook 'onboarding' / aanmelden voor toegang en developer account beheer.

Applicaties Afnemer & Applicaties Aanbieder

De applicaties van de afnemer maken gebruik van de diensten van de dienstenaanbieder door het aanroepen van API's. De applicaties van de aanbieder leveren de diensten door het aanbieden van API's.

Identity Management

In gevallen waar de identiteit van de dienstenaanvrager van belang is en onderdeel van de toegangs controle en gebruiksmonitoring, is de relatie met het identity management systeem van de organisatie relevant.
(Zie ook : https://www.noraonline.nl/wiki/Begrippen_IAM)

Punten voor verdere uitwerking in vervolgtrajecten: -Certificering van (mobile) apps / afnemer applicaties -Afspraken / standaarden 'Overheid 2 Overheid' (gesloten) API's -Centrale voorzieningen in de GDI mbt API's bv API-register

Website:

De impact van API's op de architectuur van alle organisaties die hier serieus mee aan de slag gaan is groot, net als de behoefte aan kennis op dit gebied. De werkgroep Architectuur buigt zich over vragen rond de volgende onderwerpen: de impact van het gebruik van API’s op de gehele informatievoorziening van een organisatie, de kennisopbouw over benodigde architectuur in overheidsorganisaties en het overzicht en sturing van gewenste beweging naar het gebruiken van data in plaats van het bezitten van data.

Sec:

-beschrijving van de impact van (gebruiken van ) API’s op de eigen informatievoorziening (vanuit bestaande use-cases)

-Werken aan kennis opbouw over de benodigde architectuur voor het kunnen werken met API’s

-sturing en richting geven aan de noodzakelijke beweging van data ‘hebben’ naar data ‘gebruiken’ bij het werken met API’s.

1. De GitHub tekst over REST API architectuur wordt een tekst over architectuurthema’s (beveiliging, logging, semantiek, doelbinding etc) om organisaties en mensen die zich aan het informeren zijn over REST API’s ’s om hen te helpen bij beslissingsondersteuning

2. De architectuur tekst in GitHub wordt nog geen referentie architectuur: daarvoor zijn API , methodieken, technieken, standaarden etc op dit moment in 2018 nog teveel in ontwikkeling en onvoldoende stabiel

3. Daar waar mogelijk meer stabiele architectuur elementen worden voorzien, kunnen deze van bv principes, begrippen, bouwstenen, standaarden, wettelijke grondslagen, beleid en kaders voorzien. Dit is een eerste stap richting in een nog uit te werken referentie architectuur

4. Hoofdmoot van het stuk zal zijn om stapsgewijs voor te sorteren op die elementen, methodieken en technieken die mogelijk stabiel genoeg kunnen gaan worden

5. Bijvoorbeeld rond NLX: <https: nlx.io="" about="">

6. Daarmee geeft de werkgroep Architectuur API inrichting van de NORA Applicatielaag vanuit API persperctief: <https: www.noraonline.nl="" wiki="" applicatielaag="">

De werkgroep leden hebben in november 2018 gekozen voor de volgende thematische indeling:

6.2.3 Beveiliging

6.2.4 Autorisatie

6.2.5 Semantiek

Noemen: ontwikkelingen op het gebied van Linked (open) Data, stelsel van overheidsgegevens en link: <https: www.noraonline.nl="" wiki="" semantiek="">

6.2.6 Metadata

?Noemen: Toepassingsprofiel Metadata Rijk, TMLO? Relatie leggen. <https: www.noraonline.nl="" wiki="" metagegevens_duurzame_toegankelijkheid="">

6.2.7 Interoperabiliteit

?Benadrukken voordelen voor interoperabiliteit. <https: www.noraonline.nl="" wiki="" interoperabiliteit="">

6.2.8 Patronen

Principes ondersteunen het proces om te komen tot nauwkeurige afbakening en definities van API’s van eenzelfde type. Daarnaast bevorderen zij over de verschillende bronnen heen het eenduidig gebruik van API’s voor overeenkomstige concepten. In de visualisatie hieronder is de structuur van de principes zichtbaar. Het blauw gekleurde principe is overkoepelend. Verder passen de overige principes binnen verschillende architectuurpatronen van API’s die ook in onderstaand figuur wordt weergegeven (zie oranje gekleurde principes).

6.2.8.4 Patroon ‘Terugmelden’

Een systeemgebeurtenis (zoals het verwerken van een antwoord door de afnemer) triggert een proces. Dit proces kan leiden tot het verrichten van een terugmelding, aangezien de afnemer twijfelt aan de juistheid van de gegevens. De afnemer signaleert dit richting bronhouder.

API-01: Een afnemer verricht een terugmelding bij gerede twijfel aan de juistheid van de gegevens. Gegevens in bronregistraties moeten actueel en betrouwbaar zijn. Terugmelden is één van de instrumenten om de kwaliteit van registraties te borgen. Iedere terugmelding draagt bij aan het verbeteren van een overheidsadministratie. Afnemers van de registraties hebben daarom de wettelijke plicht om mogelijk onjuiste gegevens te melden als het gaat om authentieke gegevens. Voor niet-authentieke gegevens geldt die verplichting niet. Het proces van terugmelden zorgt ervoor dat de fout in de registratie wordt gesignaleerd en na onderzoek door de bronhouder zo nodig wordt hersteld, waardoor alle afnemers vervolgens het juiste gegeven kunnen gebruiken. Het proces van Terugmelden onderscheidt 3 fasen:

• De signalering van mogelijk onjuiste gegevens door de afnemer of de betrokkene (correctierecht).
• Het in onderzoek nemen van het gemelde gegeven door de bronhouder.
• De correctie en beschikbaarstelling van het gemelde gegeven aan de afnemer die het gegeven had gesignaleerd en afnemers die zijn geabonneerd op wijzigingen van de desbetreffende gegevens (dit behoort weer tot het patroon ‘Bijhouden’).

De verschillende patronen zijn aan elkaar gerelateerd en hebben een duidelijke afhankelijkheid. Dit is in onderstaand figuur afgebeeld. Per patroon is ook aangegeven hoe gebeurtenissen, processen en datastromen zich tot elkaar verhouden.

6.2.9 Componenten

Hamvraag: zijn REST API’s bouwstenen (architectuur component)? Behandelen: op welke wijze API’s eenduidig zijn te beschrijven en vindbaar te maken zijn. Wat kunnen we (concreet) van hieruit aan richtinggevende normen/ regels voor API Register’s meegeven? Wie hebben er een use case rond een API register?

6.2.10 Begrippen

Noemen/ overnemen begrippen uit document BFS over API’s. Proberen een steeds meer gestandaardiseerd begrippenkader voor REST API’s neer te zetten

6.2.11 Standaarden

Updaten en overnemen lijst met API standaarden uit het document BFS (Lancelot Schellevis)

6.2.12 Use cases

Iig: use case Drechtsteden. Overige? Let wel: use cases zijn in dit stadium het uitgangspunt

6.2.13 Architectuur bijlagen

Bijgevoegd document:

Werkgroep Architectuur\Werkgroep_API_Architectuur Draft D[29148].pdf