Van APIs naar API's

overleggen/Werkgroep API strategie en beleid/Werkversie/strategie-overheid.md

@@ -4,24 +4,23 @@ De API first strategie past binnen de huidige beleidsdoelen en de omgeving van d
 ## Beleidsdoelen
 
 Om de beleidsdoelen van de overheid te halen is doorontwikkeling van de digitale overheid van groot belang. API koppelvlakken kunnen hierin een rol spelen om informatie eenvoudig en veilig uit te wisselen tussen overheden onderling en tussen overheden en burgers of bedrijven. 
-Een aantal beleidsdoelen waarin APIs een rol kunnen spelen (met het voor APIs relevante sleutelwoord in _cursief_) zijn:
+Een aantal beleidsdoelen waarin API's een rol kunnen spelen (met het voor API's relevante sleutelwoord in _cursief_) zijn:
 * Transparante overheid. In het kader van de [Wet Open Overheid](https://www.rijksoverheid.nl/onderwerpen/wet-open-overheid-woo) wil de overheid ondermeer _hergebruik van open data_ stimuleren. Zie ook de [Open Data Directive van de EU.](https://digital-strategy.ec.europa.eu/nl/policies/psi-open-data)
 * [Regie op gegevens.](https://www.digitaleoverheid.nl/overzicht-van-alle-onderwerpen/regie-op-gegevens/) Hierbij is het doel om burgers en bedrijven te ondersteunen bij regie op hun gegevens, die door de overheid verzameld en gebruikt worden. Dit resulteert in een sector-overstijgend kader dat _veilige, betrouwbare en gebruiksvriendelijke digitale uitwisseling van gegevens_ tussen overheden, private en maatschappelijke organisaties mogelijk maakt. Veiligheid en betrouwbare gegevensuitwisseling kan worden gewaarborgd door toepassing van de API Design Rules. 
 * [Digitale inclusie](https://www.digitaleoverheid.nl/overzicht-van-alle-onderwerpen/digitale-inclusie/) Door gegevens _via een API first strategie_ openbaar te maken kunnen gedifferentieerde gebruikersinterfaces die voor minder digitaal vaardige burgers bruikbaar zijn.  
-* [Datagedreven werken](https://www.rijksoverheid.nl/documenten/rapporten/2019/07/31/data-gedreven-werken-wat-is-er-voor-nodig)
 * De [Interbestuurlijke Data Strategie (IBDS)](https://realisatieibds.pleio.nl/) is het resultaat van nauwe samenwerking tussen departementen, uitvoeringsorganisaties en koepels van medeoverheden. Het programma zorgt ervoor dat het makkelijker wordt om binnen de overheid verantwoord met data te werken. Een van de speerpunten van het IBDS is het ontwikkelen van overheidsbrede systeemfuncties waaronder een federatief datastelsel waarmee data beter _vindbaar en technisch uitwisselbaar_ wordt.
 * [EU Data Act of _Datawet_](https://digital-strategy.ec.europa.eu/nl/policies/data-act) De datawet is gericht op eerlijke toegang tot en het gebruik van gegevens. Hierbij worden met name _Internet of Things_ (IoT) apparaten genoemd en middelen voor openbare lichamen om toegang te krijgen tot gegevens die in het bezit zijn van de particuliere sector. De datawet maakt deel uit van de Europese datastrategie.
 
 Voor al deze beleidsdoelen geldt dat APIs er een rol in kunnen spelen maar dat de API standaarden en best practices er nog niet altijd in beeld zijn.
 
 ## Omgeving
-Tot de omgeving van een publieke organisatie hoort iedereen die interactie heeft of wil hebben met een publieke organisatie. Burger, bedrijf, ketenpartner of andere organisaties uit de publieke sector. De omgeving van een organisatie uit de publieke sector is al jaren bekend met APIs en de toepassing ervan. Zo herkent iedere burger hoe eenvoudige verschillende platforms uit de platform economie (Google Amazon Linkedin Meta) eenvoudig elkaars functionaliteit integreren. Denk aan de store in store concepten op bij grote online retailers, knoppen om informatie te delen op je favoriete sociale medium. 
-Het bedrijfsleven weet hoe via PSD2 de functionaliteit en data van de bankwereld via APIs is opengebroken en interoperabel gemaakt is. Men weet ook hoe functionaliteit als betalingen, klantrelatiesystemen, boekhoudpakketten en salaris administratie middels APIs met elkaar te integreren zijn. 
-De grootste kennis in de markt van (potentiële) software leveranciers in de publieke sector voor het verbinden van IT systemen ligt mede om bovengenoemde redenen bij RESTful APIs.
-In de publieke sector zelf zijn APIs in sommige sectoren ook al dominant, CBS ontsluit al haar statistische informatie al meer dan 10 jaar via APIs, het digitaal stelsel omgevingswet heeft ze van begin af aan omarmt, het KNMI en het Kadaster en vele anderen bieden hun open data via APIs aan zodat anderen deze kunnen hergebruiken. 
-APIs pas je dus toe om goed aan te sluiten op de verwachtingen van je omgeving. 
-Niet alle organisaties zijn zo ver, sommige cruciale bedrijfsprocessen draaien nog op oude (maar meestal ook zeer stabiele) systemen die bedacht zijn voordat APIs gemeengoed werden in de IT. Je zal hen moeten blijven bedienen tot zij de omslag hebben kunnen maken. Die omslag maken is vaak niet eenvoudig, in de bankwereld was er de PSD2 wetgeving nodig om dit te laten gebeuren. 
-In de gemeentelijk wereld wordt deze omslag gemaakt in het common ground initiatief. Net als bij PSD2 worden APIs ook bij common ground ingezet als transitie mechanisme. APIs worden gebruikt om in stappen over te gaan naar nieuwe manier van werken waarbij APIs het ontkoppelpunt vormen.
+Tot de omgeving van een publieke organisatie hoort iedereen die interactie heeft of wil hebben met een publieke organisatie. Burger, bedrijf, ketenpartner of andere organisaties uit de publieke sector. De omgeving van een organisatie uit de publieke sector is al jaren bekend met API's en de toepassing ervan. Zo herkent iedere burger hoe eenvoudige verschillende platforms uit de platform economie (Google Amazon Linkedin Meta) eenvoudig elkaars functionaliteit integreren. Denk aan de store in store concepten op bij grote online retailers, knoppen om informatie te delen op je favoriete sociale medium. 
+Het bedrijfsleven weet hoe via PSD2 de functionaliteit en data van de bankwereld via API's is opengebroken en interoperabel gemaakt is. Men weet ook hoe functionaliteit als betalingen, klantrelatiesystemen, boekhoudpakketten en salaris administratie middels API's met elkaar te integreren zijn. 
+De grootste kennis in de markt van (potentiële) software leveranciers in de publieke sector voor het verbinden van IT systemen ligt mede om bovengenoemde redenen bij RESTful API's.
+In de publieke sector zelf zijn API's in sommige sectoren ook al dominant, CBS ontsluit al haar statistische informatie al meer dan 10 jaar via API's, het digitaal stelsel omgevingswet heeft ze van begin af aan omarmt, het KNMI en het Kadaster en vele anderen bieden hun open data via API's aan zodat anderen deze kunnen hergebruiken. 
+API's pas je dus toe om goed aan te sluiten op de verwachtingen van je omgeving. 
+Niet alle organisaties zijn zo ver, sommige cruciale bedrijfsprocessen draaien nog op oude (maar meestal ook zeer stabiele) systemen die bedacht zijn voordat API's gemeengoed werden in de IT. Je zal hen moeten blijven bedienen tot zij de omslag hebben kunnen maken. Die omslag maken is vaak niet eenvoudig, in de bankwereld was er de PSD2 wetgeving nodig om dit te laten gebeuren. 
+In de gemeentelijk wereld wordt deze omslag gemaakt in het common ground initiatief. Net als bij PSD2 worden API's ook bij common ground ingezet als transitie mechanisme. APIs worden gebruikt om in stappen over te gaan naar nieuwe manier van werken waarbij API's het ontkoppelpunt vormen.
 
 ## API first
 Tot de omgeving van een publieke organisatie hoort iedereen die interactie heeft of wil hebben met een publieke organisatie. Burger, bedrijf, ketenpartner of andere organisaties uit de publieke sector. 
@@ -45,14 +44,14 @@ Als organisatie uit de publieke sector druk je kosten door zoveel mogelijk gebru
 Het volgen van standaarden als de REST API design rules is in het belang van de kosten van de overheid in zijn geheel omdat breed gebruik van de standaard interoperabiliteit, wendbaarheid en bijkomende kostenvoordeel voor de hele publieke sector bewerkstelligt.
 
 
-## Actie 3: Deel Kennis over toepassen van APIs
-Je staat als organisatie in de publieke sector in de uitvoering nooit alleen. Je maakt de functionaliteit niet alleen, je werkt altijd in een keten met andere overheden en niet overheden. De kern van de samenwerking zit voor een significant deel in de koppeling. Daarom is het op een uniforme manier aanpakken van de APIs die daar invulling aan geven van belang. Als organisatie in de publieke sector deel je kennis over hoe je dat doet met de hele publieke sector en maakt waar mogelijk hergebruik van wat anderen al hebben gemaakt. Voor APIs doen we dat binnen het kennisplatform APIs. Daar maken we standaarden en best practices die we met elkaar delen. Het gaat hier om standaarden voor uniformiteit, en interoperabiliteit van APIs, maar ook voor over ontwerpkeuzes binnen APIs, voor de IT architectuur waarbinnen ze gebruikt worden als ook over de vindbaarheid van APIs. We streven ernaar deze binnen bestaande gremia zoals de lijst verplichte standaarden van het forum standaardisatie voor standaarden en de NORA voor architectuur vast te stellen.
+## Actie 3: Deel Kennis over toepassen van API's
+Je staat als organisatie in de publieke sector in de uitvoering nooit alleen. Je maakt de functionaliteit niet alleen, je werkt altijd in een keten met andere overheden en niet overheden. De kern van de samenwerking zit voor een significant deel in de koppeling. Daarom is het op een uniforme manier aanpakken van de API's die daar invulling aan geven van belang. Als organisatie in de publieke sector deel je kennis over hoe je dat doet met de hele publieke sector en maakt waar mogelijk hergebruik van wat anderen al hebben gemaakt. Voor API's doen we dat binnen het kennisplatform API's. Daar maken we standaarden en best practices die we met elkaar delen. Het gaat hier om standaarden voor uniformiteit, en interoperabiliteit van API's, maar ook voor over ontwerpkeuzes binnen API's, voor de IT architectuur waarbinnen ze gebruikt worden als ook over de vindbaarheid van API's. We streven ernaar deze binnen bestaande gremia zoals de lijst verplichte standaarden van het forum standaardisatie voor standaarden en de NORA voor architectuur vast te stellen.
 
 
-## Actie 4: Zorg dat APIs vindbaar zijn
-Het is niet alleen belangrijk om APIs aan te bieden, ze moeten ook door de omgeving gevonden kunnen worden. 
+## Actie 4: Zorg dat API's vindbaar zijn
+Het is niet alleen belangrijk om API's aan te bieden, ze moeten ook door de omgeving gevonden kunnen worden. 
 Het is belangrijk om een balans te vinden tussen vindbaarheid en vereiste inspanning om alle publieke informatie op verschillende plekken actueel te houden.
-Vindbaarheid verhoog je door het voor makers van APIs zo laagdrempelig mogelijk te maken om APIs te publiceren. 
-Praktisch zijn er, afhankelijk van de ambitie en middelen van een organisatie, meerdere manieren voor. Je kan een eigen developer portaal bouwen waar je APIs ontsluit toegang regelt (indien nodig) en zorgt voor goede documentatie. Je kan ook hergebruik maken van de catalogi en portalen die de overheid biedt. 
-We werken als publieke sector aan afspraken (zoals in het Federatief Data Stelsel) om de vindbaarheid van APIs in catalogi en portalen te vergroten waarbij het streven is dat informatie over APIs eenmalig door de aanbieder wordt aangeleverd en in meerdere catalogi en portalen kan worden hergebruikt.
-APIs moeten waar mogelijk (binnen grenzen openbaarheid) centraal en publiekelijk vindbaar zijn, dus niet alleen via de kanalen van de aanbiedende organisatie maar ook vanuit landelijke portalen/catalogi.
+Vindbaarheid verhoog je door het voor makers van API's zo laagdrempelig mogelijk te maken om API's te publiceren. 
+Praktisch zijn er, afhankelijk van de ambitie en middelen van een organisatie, meerdere manieren voor. Je kan een eigen developer portaal bouwen waar je API's ontsluit toegang regelt (indien nodig) en zorgt voor goede documentatie. Je kan ook hergebruik maken van de catalogi en portalen die de overheid biedt. 
+We werken als publieke sector aan afspraken (zoals in het Federatief Data Stelsel) om de vindbaarheid van API's in catalogi en portalen te vergroten waarbij het streven is dat informatie over API's eenmalig door de aanbieder wordt aangeleverd en in meerdere catalogi en portalen kan worden hergebruikt.
+API's moeten waar mogelijk (binnen grenzen openbaarheid) centraal en publiekelijk vindbaar zijn, dus niet alleen via de kanalen van de aanbiedende organisatie maar ook vanuit landelijke portalen/catalogi.