API Strategie Algemeen (Nederlandse API Strategie I)

Geonovum Handreiking
Versie ter vaststelling

Deze versie:
https://docs.geostandaarden.nl/api/vv-hr-API-Strategie-20200117/
Laatst gepubliceerde versie:
https://docs.geostandaarden.nl/api/API-Strategie/
Vorige versie:
https://docs.geostandaarden.nl/api/vv-hr-API-Strategie-20190715/
Laatste werkversie:
https://geonovum.github.io/KP-APIs/
Redacteurs:
Frank Terpstra, Geonovum
Jan van Gelder, Geonovum
Auteurs:
Lancelot Schellevis, Forum Standaardisatie
Han Zuidweg, Forum Standaardisatie
Friso Penninga, Geonovum
Matthias Snoei, Swis
Jasper Roes, Het Kadaster
Peter Haasnoot, Logius
Doe mee:
GitHub geonovum/KP-APIs
Dien een melding in
Revisiehistorie
Pull requests
Rechtenbeleid:

Samenvatting

Dit document beschrijft een API strategie voor de Nederlandse overheid.

Status van dit document

Deze paragraaf beschrijft de status van dit document ten tijde van publicatie. Het is mogelijk dat er actuelere versies van dit document bestaan. Een lijst van Geonovum publicaties en de laatste gepubliceerde versie van dit document zijn te vinden op https://www.geonovum.nl/geo-standaarden/alle-standaarden.

Dit is een definitief concept van de nieuwe versie van de handreiking. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.

Ten opzichte van de vorige versie van de API strategie (15-7-2019) zijn geen inhoudelijke aanpassingen gedaan, de wijzigingen zijn alleen redactioneel, het document is opgesplitst. De API designrules (voorheen Hoofdstuk 4) is een los document geworden.

1. Inleiding

Dit onderdeel is niet normatief.

Dit hoofdstuk geeft een inleiding op de Nederlandse API strategie

1.1 Status van de API strategie

In deze versie van de API strategie zijn de op en aanmerkingen uit de consultatie verwerkt. Op GitHub kan bekeken worden wat er precies is gedaan met de op en aanmerkingen.

1.2 Auteurs

Er worden slechts 6 auteurs genoemd, echter aan deze strategie is door veel meer mensen gewerkt. De genoemde auteurs zijn de 6 trekkers van de 5 werkgroepen API Strategie, Architectuur, Authenticatie en Autorisatie, Communicatie en Beleid, en Gebruikerswensen

1.3 Leeswijzer

Dit document is onderdeel van de "Nederlandse API Strategie"

Deel Omschrijving Status Link
I Algemene beschrijving van de API Strategie Informatief https://docs.geostandaarden.nl/api/API-Strategie/
IIa Standard for designing APIs Normatief https://docs.geostandaarden.nl/api/API-Designrules/
IIb Extensie van de Standaard voor API ontwerp Informatief https://docs.geostandaarden.nl/api/API-Strategie-ext/

Dit document bevat twee delen, waarbij het eerste deel "niet-technisch" en het tweede deel "technisch" van aard is. In het eerste deel zitten de hoofdstukken Communicatie en Beleid en Gebruikerswensen.

Het tweede deel bevat de hoofdstukken Standaarden en Architectuur, waarin een technische uitwerking van de eerste twee hoofdstukken staat.

2. Communicatie en beleid

Dit onderdeel is niet normatief.

Dit hoofdstuk geeft een niet-technische inleiding voor bestuurders en managers. In dit hoofdstuk bekijken we:
- welk probleem willen we oplossen?
- wat zijn APIs en hoe helpen ze bij dit probleem?
- wanneer zijn APIs relevant voor mijn organisatie?
- voorbeelden van het gebruik van APIs in Nederland

Larissa gaat verhuizen van Den Haag naar Amsterdam. Ze gaat naar het gemeentehuis in Amsterdam om zich in te schrijven. Achter de schermen komt er een ingewikkelde gegevensstroom op gang.

Amsterdam en Den Haag houden elk hun eigen registratie van personen bij. De ICT systemen van Amsterdam moeten daarom de persoonsgegevens van Larissa opvragen bij de ICT systemen van Den Haag. Daarna kan Amsterdam Larissa in z’n eigen basisregistratie personen registreren. De gemeente Den Haag moet weten dat Larissa nu in Amsterdam staat ingeschreven. Dus stuurt Amsterdam verwijsgegevens voor Larissa naar Den Haag. Den Haag verwerkt de verwijsgegevens voor Larissa in z’n lokale basisregistratie personen. Zowel Amsterdam als Den Haag moeten de mutaties van hun lokale basisregistratie personen ook nog doorgeven aan de centrale basisregistratie personen van de Autoriteit Persoonsgegevens (BRP). Zo kan het drie werkdagen kosten om een eenvoudige verhuizing volledig te registreren.

Is het niet efficiënter om één basisregistratie personen bij te houden, in plaats van gegevens heen en weer te schuiven van de ene lokale registratie naar de andere?

Visualisatie van de voordelen van het bij de bron houden van data met APIs

2.1 De digitale overheid heeft een probleem

Bij veel ICT systemen van de overheid zitten de gegevens (de data) helemaal verweven in de applicatie. Ieder systeem heeft z'n eigen database en kopieert data van en naar andere systemen. Zo werken veel systemen bij gemeenten met kopieën van de landelijke basisregistraties. Met de jaren ontstaat daardoor een wirwar aan koppelingen tussen systemen.

Visualisatie van de ongestructureerde datakoppelingen tussen ICT systemen van de overheid. Bron: VNG Realisatie. Bron: VNG Realisatie.

De huidige situatie brengt een aantal problemen met zich mee:

  1. De kans op fouten en datalekken neemt toe bij het veelvuldig kopiëren en gedupliceerd opslaan van gegevens.
  2. Het kopiëren en synchroniseren van gegevens tussen systemen kost tijd, resources en geld.
  3. Personen of bedrijven hebben geen regie over hun gegevens als deze overal verspreid staan.
  4. Veel van de systemen en koppelingen werken afhankelijkheid van leveranciers in de hand.

We kunnen de digitale overheid veiliger, efficiënter en beter beheersbaar maken door applicaties beter te scheiden van de gegevens en de gegevens alleen bij de bron te bewaren. Door de gegevens alleen door de bronhouder te laten beheren, hoeven ze niet meer op grote schaal gekopieerd, gedupliceerd en gesynchroniseerd te worden. Dit idee zit achter het nieuwe gegevenslandschap met als onderdelen Haal Centraal en Common Ground.

Dit vraagt om technologie waarmee je gegevens op een betrouwbare en schaalbare manier kan ontsluiten bij de bron. Dat kan met APIs.

2.2 Wat is een API?

Een application programming interface (API) is een gestructureerd en gedocumenteerd koppelvlak voor communicatie tussen applicaties. Je kan een API zien als een digitale stekkerdoos die applicaties met elkaar verbindt. APIs bestaan al zo lang er computers zijn.

Hier hebben wij het in het bijzonder over APIs waarmee je applicaties over het Internet kan koppelen. Zogenaamde REST APIs doen voor applicaties wat websites voor mensen doen. Websites presenteren informatie aan mensen, REST APIs maken applicaties en gegevens over het Internet beschikbaar voor andere applicaties. De technologie achter websites en REST APIs heeft daarom veel gemeen.

De meeste applicaties gebruiken APIs onder de motorkap zonder dat de eindgebruiker dat ziet. Als je een app opent voor het weer, dan merk je niet dat deze app gegevens ophaalt bij het KNMI via een API. Degene die het meest direct met een API te maken krijgt is de ontwikkelaar van de applicatie die de API gebruikt. Zij moet begrijpen hoe de API werkt en hoe je deze vanuit de applicatie moet bevragen.

Hier verschillen APIs dus van websites. Een website bouw je voor de eindgebruiker die hem bezoekt. Een API maak je voor programmeurs die er applicaties mee bouwen. Daarom is het gewoonte om APIs aan te bieden op het developer subdomein van een website, zoals developer.overheid.nl voor APIs van de overheid.

2.3 Wat betekenen APIs voor mijn organisatie?

APIs zijn een middel, geen doel. De missie van een organisatie bepaalt of APIs toegevoegde waarde hebben in de ICT processen. Dat kan het geval zijn als de organisatie een dienstverlenende taak heeft en gegevens beheert die andere organisaties gebruiken. Of als de organisatie deel uit maakt van een of meer ketens.

Een aantal zaken om te overwegen:

  1. Gegevens bij de bron beheren. Voorkom het dupliceren en lokaal bewerken van centrale gegevensverzamelingen. Dit maakt processen efficiënter en voorkomt dat kopieën van gegevensverzamelingen uit de pas lopen.
  2. Processen en gegevens losser koppelen. Vaste ketens maken steeds vaker plaats voor lossere koppelingen met een kortere levensduur, zoals in de visie van Common Ground. Of in smart cities als Amsterdam waar een wisselende groep publieke en private organisaties dynamisch gegevens uitwisselt.
  3. Specifieke vragen bedienen. Afnemers hebben meestal niet alle gegevens uit je gegevensverzameling nodig. Voorbeeld: een applicatie die in de Basisregistratie Adressen en Gebouwen het adres opzoekt dat hoort bij een postcode en huisnummer hoeft niet het bouwjaar, oppervlakte en gebruiksdoel van het pand te krijgen.
  4. ICT projecten 'Agile' uitvoeren. Steeds meer organisaties zoals Logius ontwikkelen systemen volgens Agile principes. Dit betekent dat je snel in moet kunnen spelen op veranderende vragen van de gebruikers aan je gegevensbronnen.
  5. Afhankelijkheid van leveranciers verminderen. Voorkom dat koppelingen maatwerk vereisen of afhankelijk zijn van producten of kennis van een specifieke leverancier. Gebruik waar mogelijk open standaarden.
  6. Innovatie stimuleren. Door gegevens openbaar aan te bieden kunnen zowel publieke als private ondernemingen ermee aan de slag. Zij gebruiken de gegevens soms op verrassende manieren die nieuwe kansen creëren.
  7. Wettelijke verplichting. Er komt steeds meer wettelijke verplichting om herbruikbare overheidsdata te publiceren. In de recentere wetgeving wordt het gebruik van APIs expliciet verplicht voor bepaalde data. Bijvoorbeeld in de Europese richtlijn die in 2021 zal leiden tot een herziening van de Wet Hergebruik van Overheidsinformatie.

Inventariseer welke gegevens je organisatie voortbrengt en welke gegevens je gebruikt van andere organisaties. Bekijk hoe de bestaande ICT koppelingen ingericht zijn. Is je organisatie daarbij afhankelijk van bepaalde producten of leveranciers? Kan het efficiënter, flexibeler, veiliger en meer open met APIs?

Deze API strategie beschrijft de standaarden, ontwerpprincipes en veiligheidsmaatregelen die ervoor zorgen dat alle overheden hun APIs op een inzichtelijke, gebruikersvriendelijke, veilige en geharmoniseerde manier aanbieden. Door deel te nemen in het Kennisplatform APIs krijgt je organisatie meer inzicht in de toegevoegde waarde die APIs voor jouw toepassing al dan niet kunnen bieden.

2.4 Nederland heeft al schitterende voorbeelden

Veel publieke organisaties in Nederland bieden hun gegevens met APIs aan. De Nederlandse Spoorwegen bijvoorbeeld, die met APIs actuele vertrektijden, prijzen, storingen en reisadviezen publiceren om in apps te gebruiken. En de Rijksdienst voor het Wegverkeer die de kentekenregistratie voor voertuigen met een API aanbiedt.

In februari 2019 won de Basisregistratie Adressen en Gebouwen (BAG) API van Kadaster de Gouden API die het Kennisplatform APIs uitloofde voor de beste API van de overheid. De BAG registreert voor elk adres in Nederland gegevens als de geografische coördinaten, het bouwjaar van het pand, de oppervlakte en het vergunde gebruiksdoel. Verzekeraars, hypotheekverstrekkers, hulpdiensten, milieudiensten en vele anderen gebruiken informatie uit de BAG. Dat de BAG API voldoet aan een behoefte blijkt wel uit de 300 miljoen consultaties die de BAG API in 2018 verwerkte.

De APIs van Luchtmeetnet en van de Kamer van Koophandel kregen bij de Gouden API eervolle vermeldingen vanwege hun relevantie en gebruiksgemak. De API van de Kamer van Koophandel geeft applicaties toegang tot de gegevens van het handelsregister. Hiermee kunnen bijvoorbeeld bedrijven en gemeenten CRM systemen, zaaksystemen en factureringssystemen aan het handelsregister koppelen. De API van Luchtmeetnet geeft bijvoorbeeld weer-apps de mogelijkheid om ook informatie over luchtkwaliteit voor astmatici te geven.

Het portal developer.overheid.nl geeft een overzicht van APIs die Nederlandse overheidsorganisaties aanbieden. Heeft jouw organisatie gegevens waar bedrijven, burgers of andere overheden iets mee kunnen?

3. Inspelen op gebruikerswensen: dé sleutel tot gebruik

Dit onderdeel is niet normatief.

3.1 Inleiding

Overheden bezitten kwalitatief hoogwaardige data en bieden deze aan via API’s. Vanuit het open data-perspectief maken overheden het hiermee mogelijk dat anderen -binnen én buiten de overheid- zinvolle toepassingen kunnen ontwikkelen, die maatschappelijke meerwaarde bieden. Maar de overheid gaat nog verder: bij initiatieven als Common Ground is het gebruik van API’s zelfs randvoorwaardelijk om werkprocessen zodanig in te richten, dat data altijd bij de bron bevraagd en gewijzigd kan worden. Een belangrijke succesfactor in deze ontwikkelingen is de mate waarin overheden erin slagen om drempels voor het gebruik van hun API’s weg te nemen. Om het gebruik zo laagdrempelig mogelijk te maken, is het essentieel dat er aandacht is voor de wensen van gebruikers. En om te begrijpen welke wensen ze hebben, is het essentieel om te begrijpen wie die gebruikers zijn. In generieke zin zijn de gebruikers van API's developers: mensen die toepassingen ontwikkelen. Deze developers fungeren als intermediair tussen de data- of dienstaanbieder enerzijds en de eindgebruiker anderzijds. Neem bijvoorbeeld een gemeente die het mogelijk wil maken dat burgers makkelijk melding kunnen maken van een defecte lantarenpaal, losliggende stoeptegel of zwerfvuil, De burger is dan de eindgebruiker, maar de ontwikkelaar van de Melding Openbare Ruimte app is de gebruiker van de API's die de gemeente aanbiedt om bijvoorbeeld een kaartondergrond op te halen of een melding aan te bieden aan de gemeente. De gebruikerswensen liggen niet alleen op het “wat” (wat voor data krijg ik?), maar zeker ook op het “hoe” (hoe makkelijk kan ik aan de slag met deze API?). Bij de eerste kennismaking met de API moet de gebruiker verleidt worden om de API te gaan gebruiken en in alle volgende fases van gebruik (implementeren, in productie nemen en in productie houden) moet de gebruikerservaring zodanig zijn, dat de gebruiker geen enkele reden heeft om af te haken. Sterker nog: idealiter wordt de gebruiker zó enthousiast over de API en de bijbehorende ondersteuning, dat de gebruiker onderdeel wordt van de gebruikerscommunity en actief gaat bijdragen aan verdere ontwikkeling en promotie van die API. Merk op dat dit effect alleen bereikt kan worden, wanneer de totaalbeleving klopt: ook al is het product (de data) zelf nog zo goed, als de gebruikservaring belabberd is, dan zul je niet veel potentiële gebruikers verleiden om met je data zinvolle toepassingen te gaan ontwikkelen. En nog erger: gebruikers die tóch met de API aan de slag gaan, zullen de helpdesk van de aanbieder zwaar gaan belasten, de data mogelijk verkeerd gaan interpreteren en de ICT-infrastructuur onnodig zwaar belasten, wanneer zij slechts omslachtig (met veel API-calls) de gewenste gegevens kunnen krijgen.

3.2 Overkoepelende aanbeveling: biedt een goede ‘developer experience (DX)’

De belangrijkste aanbeveling aan aanbieders van API’s is om zich te richten op die gebruikservaring; op een goede ‘developer experience (DX)’. Goede DX komt voort uit stapeling van aandacht voor functionality (functionaliteit - wat moet de API doen?), voor usability (hoe bruikbaar is de API voor de developer?) en daar bovenop voor de experience (hoe voelt de developer zich als die de API gebruikt?). Dat laatste aspect -hoe voelt de developer zich- klinkt wellicht wat vaag, maar het is in essentie de optelsom van ervaringen in de interactie tussen een developer en een API aanbieder. Stel: een developer, Johan (26 jaar – ZZP-er), heeft moeite om een bepaalde API te vinden, vervolgens blijkt het registratieproces lastig en krijgt hij de API key pas een week later, daarna blijkt de documentatie in voor Johan deels onbegrijpelijk jargon geschreven (én is het ook nog eens een PDF van 352 pagina’s), dan heeft Johan meerdere calls nodig om de gewenste data te krijgen en uiteindelijk is data helemaal niet in het door Johan gewenst formaat. Elke kleine irritatie is op zichzelf niet onoverkomelijk, maar de optelsom maakt dat Johan concludeert: “Dit is niet te doen, ik zoek wel wat anders!”.

3.3 Gebruik: van ‘onboarding’ tot ‘in productie’

De zwakte van veel teksten over ‘developer experience’ is dat men zich vaak alleen richt op de use case van een technische developer die een API wil implementeren - denk aan Johan in de vorige paragraaf. Gebruik begint echter niet bij de poging tot implementatie; hier gaan nog stappen aan vooraf. Johan heeft zich al een aantal vragen gesteld, voordat hij besloot om die poging te wagen. Die vragen -en daarmee de stappen die hij doorloopt- zijn beter te introduceren aan de hand van het voorbeeld van een grotere softwareleverancier. Stel: Anne (43 jaar) werkt als product manager bij een commerciële softwareleverancier en heeft een aantal applicaties voor de gemeentelijke markt in haar portfolio. Ze ziet een API op een ontwikkelaarsportaal en beoordeelt aan de hand van de functionele specificaties of implementatie van de API meerwaarde biedt voor één van haar applicaties. Eén API trekt haar aandacht en Anne vraagt Steven (56 jaar, architect bij hetzelfde bedrijf) om te beoordelen of de API past binnen de software stack van het bedrijf en kritisch te kijken naar eventuele security en privacy issues. Steven ziet mogelijkheden en vervolgens krijgt Jeffrey (37 jaar, software engineer bij hetzelfde bedrijf) de opdracht om binnen een dag te beoordelen of hij de API succesvol kan integreren in de nieuwe versie van het product uit Anne’s portfolio. Na Jeffrey’s positieve oordeel besluit Gea, de manager, om tijd en geld vrij te maken voor implementatie. Zo komt de API uiteindelijk in de productieversie terecht: *"developer tries, business buys"*.

Dit eindresultaat is bereikt, doordat in alle fases de ‘onboarding’ -het proces dat Anne, Steven en Jeffrey doorliepen toen zij voor de eerste keer gebruik maakten van een digitale service (het aanbieden van de API)- prettig verliep. Uit marketingonderzoeken blijkt een prettige eerste gebruikerservaring van een online platform (bijvoorbeeld het ontwikkelaarsportaal waarop Anne de API ontdekte en zij vervolgens samen met Steven en Jeffrey de API beoordeelde) veel invloed heeft op het verdere gebruik ervan. Oftewel: de kans is groot dat dit bedrijf vervolgens ook andere API’s op dit ontwikkelaarsportaal gaat gebruiken.

De kern van dit verhaal is dat een API technisch gezien weliswaar een machine tot machine koppeling is, maar strategisch juist gezien moet worden als een product. En dat product moet gebruikers (zie ze als potentiële klanten!) verleiden tot gebruik. Dan zijn aspecten als de winkelervaring (in een API store of ontwikkelaarsportaal), de geboden service en de kwaliteit van het product de doorslaggevende factoren in de beslissing om tot gebruik over te gaan.

3.4 Specifieke aanbevelingen voor een goede DX

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

Een API is weliswaar een machine tot machine koppeling, maar onthoud: API's 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?”) en security- en privacy-aspecten.

  • 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: een experimenteeromgeving met testdata. 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.5.1 Aanbeveling 5.1 Stel een SLA op

Maak duidelijk welke verwachtingen een gebruiker mag hebben qua uptime, service window, beprijzing etc.

3.4.5.2 Aanbeveling 5.2 Biedt een roadmap aan

Maak duidelijk of en zo ja, wanneer er eventuele wijzigingen te verwachten zijn en hoe lang de API minimaal beschikbaar blijft.

3.4.5.3 Aanbeveling 5.3 Doe aan versiebeheer

Borg dat de toepassing van de gebruiker blijft werken, door te zorgen voor backward compatability. Grotere updates kunnen als nieuwe versie worden uitgebracht, waarbij oudere versies nog een gegarandeerde periode beschikbaar blijven. Het versienummer kan in elke call staan, bijv. GET /api/v1.0/... En versiebeheer slaat niet alleen op de API zelf, maar ook op de bijbehorende documentatie, Sandbox, etc.

3.4.5.4 Aanbeveling 5.4 Sluit de feedback-loop: betrek de community

Om echt van buiten naar binnen te kunnen werken, is het betrekken van de community van gebruikers onmisbaar. De community kan vertellen hoe de developer experience tot nu toe is, welke verbeteringen wenselijk zijn, welke gebruikersvragen er sterk leven, maar nog onvoldoende ondersteund worden, etc., etc. Daarnaast wil je de community ook actief informeren over voorgenomen wijzigingen e.d. Het gebruik van API keys is een manier om je gebruikers te kennen.

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 online te ontsluiten (zoals bijvoorbeeld in de Stelselcatalogus Omgevingswet), 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, nationaal idealiter bij developer.overheid.nl. Als een API een product is, hoort dat product ook in een goede winkel te staan. En in een succesvolle winkel is altijd goed nagedacht over productpresentatie: presenteer breed toepasbare API’s en datasets 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. Formuleer hierbij ook goed het ambitieniveau:

  • API store: de one-stop-shop, waarin je niet alleen (het bestaan van) de API ontdekt, maar ook de documentatie vindt, de API kunt uitproberen, etc. Het runnen van een API store kan zelfs zover gaan, dat er centraal proxy's worden ontwikkeld op API's van andere aanbieders en documentatie geredigeerd, om zo voor de eigen gebruikers een zo uniform mogelijke gebruikerservaring te garanderen.

  • API catalogus: uitsluitend gericht op het ontdekken van API's, waarna doorverwezen wordt naar de API store van de desbetreffende aanbieder.

  • hybride oplossing: een combinatie van een catalogus en een store. Alle API's staan in de catalogus, een kleine subset (de high-value API's) wordt volledig aangeboden. Deze hybride oplossing zou een mooi ambitieniveau voor developer.overheid.nl kunnen zijn: alle overheids-API's zijn vindbaar en voor de meest generieke en populaire API's ben je direct op de juiste plaats.

Een bijzondere categorie die de overheid ook nodig gaat hebben, o.a. door de ontwikkelingen in Common Ground, is de API spec store: een plaats waarin API specificaties gepubliceerd kunnen worden. Leveranciers kunnen op basis van die specificaties zelf hun specificatie-conforme API's ontwikkelen, waarmee de interoperabiliteit van gegevens binnen het gemeentelijke applicatielandschap wordt vergroot.

In de context van API stores en API catalogi is het belangrijk om te realiseren dat developer experience niet alleen een externe focus heeft (gericht op laten ontdekken, evalueren, testen en gebruiken van API's), maar ook een interne focus, gericht op het activeren van potentiële API-aanbieders. Zij moeten getriggerd worden om API's te ontwikkelen, te ontsluiten in je API store of catalogus, te beschrijven conform bepaalde kwaliteitseisen, etc.

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. Denk hierbij weer aan 'API als een product': ga niet blind data ontsluiten, maar begin bij de vraag welke propositie je neer wil zetten.

4. Standaarden

Dit onderdeel is niet normatief.

Binnen de Nederlandse publieke sector zijn meerdere standaarden die betrekking hebben op APIs. In dit hoofdstuk geven we verwijzingen naar de standaarden die zijn voortgekomen uit het Kennisplatform APIs. In een volgende versie van dit document zal hier een compleet overzicht met relevante standaarden komen.

4.1 API Designrules (Nederlandse API Strategie IIa)

Deze sectie beschrijft de status en uitgangspunten voor de standaard "API Designrules". De standaard is een op zichzelfstaand document en is hier te vinden:

https://geonovum.github.io/API-Designrules/ (werkversie)

https://docs.geostandaarden.nl/api/API-Designrules/ (stabiele versie)

4.1.1 Oorsprong standaard

De API designrules vinden hun oorsprong in de "API strategie" van het digitaal stelsel omgevingswet (DSO). Bij het opstellen van de API Designrules is de DSO API strategie het startpunt geweest en heeft de werkgroep API strategie (onder leiding van Jasper Roes) gekeken hoe deze toepasbaar gemaakt kunnen worden voor de hele Nederlandse publieke sector.

4.1.2 Status bij forum standaardisatie

De API designrules standaard is op 3 oktober 2019 door de stuurgroep van het Kennisplatform API's aangemeld voor opname op de "pas toe of leg uit" van het forum standaardisatie. Er zullen nog een aantal stappen moeten volgen in de procedure voordat duidelijk is of en onder welke voorwaarden de standaard daadwerkelijk wordt opgenomen.

4.1.2.1 Werkingsgebied standaard

Bij aanmelding was het beoogd organisatorisch werkingsgebied: Overheden, semi-overheden en instellingen uit de publieke sector

4.1.2.2 Toepassingsgebied standaard

Bij aanmelding was het beoogd functioneel toepassingsgebied: Het aanbieden van RESTful APIs ten behoeve van het ontsluiten van overheids informatie/functionaliteit en enkelvoudige datasets aan eenieder waarvoor deze bedoeld is(burger, bedrijf, andere overheid, etc…). Het ontsluiten van meervoudige en/of statistische datasets via één API valt buiten het functioneel werkingsgebied hiervoor staat de standaard ODATA reeds op de lijst met aanbevolen standaarden.

4.2 API Designrules extensions (Nederlandse API Strategie IIb)

Deze sectie beschrijft de status en uitgangspunten voor de standaard "API Designrules extensions". De (concept) standaard is een op zichzelfstaand document en is hier te vinden:

https://geonovum.github.io/KP-APIs/API-strategie-extensies/ (werkversie)

https://docs.geostandaarden.nl/api/vv-hr-API-Strategie-ext-20190715/ (stabiele versie)

4.2.1 Oorsprong standaard

De API designrules extensions bevatten onderwerpen die bij het opstellen van de eerste versie van de API designrules nog niet als stabiel werden beschouwd. Er wordt nog actief gewerkt om deze extensies tot een stabiele versie te maken. Uiteindelijk zal een deel van de extensies mogelijk direct onderdeel worden van de API design rules. Een ander deel zal een optionele extensie zijn die gebruikt kan worden wanneer specifieke extra functionaliteit nodig is.

4.2.2 Status

De API designrules extensions zijn nog in ontwikkeling en hebben geen enkele status.

4.2.2.1 Werkingsgebied standaard

Een werkingsgebied is (nog) niet van toepassing.

4.2.2.2 Toepassingsgebied standaard

Een toepassingsgebied (nog) niet van toepassing.

4.3 Nederlands profiel OAuth

Deze sectie beschrijft de status en uitgangspunten voor het Nederlands profiel OAuth. het profiel zelf is een op zichzelfstaand document. Het Nederlands profiel OAuth is hier te vinden: https://geonovum.github.io/KP-APIs-OAuthNL/#dutch-government-assurance-profile-for-oauth-2-0 In aanvulling hierop is er een document dat de verschillen met iGOV kort samenvat en voorziet van rationales. https://github.com/Geonovum/KP-APIs-OAuthNL/blob/master/Additional%20specification%20and%20constraints%20of%20iGov-NL%20to%20the%20iGov%20profile.md

4.3.1 Oorsprong standaard

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. Het maken van dit Nederlandse profiel is opgepakt door de werkgroep Authenticatie/Autorisatie van het Kennisplatform API's.

4.3.2 Status bij forum standaardisatie

De standaard OAuth is momenteel nog in behandeling bij het forum standaardisatie. De verwachting is dat de internationale standaard OAuth op de lijst met aanbevolen standaarden komt en het Nederlands profiel OAuth op de "pas toe of leg uit" lijst komt.

4.3.2.1 Werkingsgebied standaard

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

4.3.2.2 Toepassingsgebied standaard

Als functioneel toepassingsgebied wordt in het expert advies 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.

4.3.2.3 Bijzonderheden
4.3.2.3.1 OpenID connect buiten scope

de expertgroep van het forum standaardisatie 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. Inmiddels is OpenID connect apart voorgedragen voor opname op de "pas toe of leg uit" lijst van het forum standaardisatie. Voor deze standaard komt ook een Nederlands profiel. Dit zal ook gebaseerd zijn op iGOV zoals in de volgende sectie uitgelegd wordt.

4.3.2.3.2 Aansluiting op internationale standaard iGov

Het Nederlands profiel OAuth baseerd zich op het internationale iGOV OAuth 2.0 profiel [iGOV.OAuth2]. Niet alle keuzes van dit internationale profiel worden overgenomen aangezien dit een aantal keuzes bevat die sterk leunen op de amerikaanse situatie. Het kan het best beschouwd worden als een fork waarbij in het profiel aangeven wordt waar afwijkingen zijn. iGov heeft 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 het Nederlandse profiel OAuth uitgebreid worden met een Nederlandse variant van het iGov OpenID Connect profiel. De usecase die wordt beschreven aan het begin van het Nederlands profiel OAuth sorteert daar al op voor.

5. Architectuur

Dit onderdeel is niet normatief.

Dit hoofdstuk gaat in op de vraag: Hoe kan je je applicatie landschap inrichten zodat je APIs kan aanbieden. Welke componenten zijn hiervoor nodig. Hoe ga je om met opschalen, beschikbaarheid. Wat zijn afwegingen om beveiliging al dan niet toe te passen.

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

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

5.2.1 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;

5.2.2 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;

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

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

5.2.5 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)

A. Referenties

A.1 Informatieve referenties

[Expert]
Expertadvies OAuth 2.0. P. Dam. Forum Standaardisatie. 24 februari 2017. URL: https://www.forumstandaardisatie.nl/sites/bfs/files/Expertadvies%20OAuth%202.0.pdf
[iGOV.OAuth2]
International Government Assurance Profile (iGov) for OAuth 2.0. J. Richer, M. Varley, P. Grassi. OpenID foundation. October 5 2018. URL: https://openid.net/specs/openid-igov-oauth2-1_0.html
[iGOV.OpenID]
International Government Assurance Profile (iGov) for OpenID Connect 1.0 - draft 3. M. Varley, P. Grassi. OpenID foundation. October 5 2018. URL: https://openid.net/specs/openid-igov-openid-connect-1_0.html