API Strategie Algemeen (Nederlandse API Strategie I)

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"

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

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

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

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