API-standaarden: verschil tussen versies

Huidige versie van 30 apr 2024 om 15:24

Het wordt steeds belangrijker voor (applicatie)componenten om onderling goed samen te werken. Om dit mogelijk te maken kennen componenten (applicatie)services die voor andere componenten toegankelijk zijn via zogenaamde 'Application Programming Interfaces' (API's). Zo kunnen componenten op een gestructureerde manier functionaliteit van andere componenten gebruiken. Bijvoorbeeld door een API aan te bieden die voor andere componenten bruikbaar is om gegevens uit een achterliggende bronregistratie te gebruiken.

Om doelmatig en efficiënt met API's te werken is het belangrijk om de manier waarop API's worden ontwikkeld, gedocumenteerd, getest en werken te standaardiseren. Er zijn een aantal manieren om dit te realiseren. Een daarvan is het kiezen voor een bepaalde architectuurstijl. Net als in de rest van de wereld geldt ook voor de Nederlandse overheid dat de voorkeur momenteel uitgaat naar API's die werken volgens de REST-architectuurstijl. Maar dan nog geldt dat er aanvullende ontwerpkeuzes moeten worden gemaakt. Daarom is afgesproken om overheidsbrede afspraken te maken over hoe de REST-stijl wordt toegepast bij het ontwerpen van API's. Deze afspraken zijn vastgelegd in de REST-API Design Rules standaard.

Op de website developer.overheid.nl is te zien dat er steeds meer overheids-API's beschikbaar komen die allerlei soorten functionaliteit aanbieden. Op data.overheid.nl worden (ook) API-specificaties gepubliceerd waarmee open data is op te vragen. Voor gemeenten zijn met name API's interessant waarmee elders vastgelegde brongegevens toegankelijk worden gemaakt. Gebruik daarvan kan bijvoorbeeld leiden tot hogere actualiteit en betrouwbaarheid van data en het onderhouden van lokale kopieën overbodig maken.

De GEMMA Architectuurvisie beschrijft hoe standaardisatie via het gebruik van API's cruciaal is om toe te kunnen werken naar een fundamenteel betere informatievoorziening voor gemeenten. Iets dat verder wordt uitgewerkt binnen de thema-architectuur Common Ground die de architectuur uitwerkt die nodig is om de doelen van Common Ground te realiseren.

Vanuit de VNG wordt op verschillende manieren gewerkt aan de ontwikkeling van gestandaardiseerde API's:

Via het programma HaalCentraal is gewerkt aan het ontwikkelen van de HaalCentraal API's zodat gemeenten beter data kunnen opvragen uit de basisregistraties.
Het project Notificatieservices heeft een concept-standaard ontwikkeld voor het notificeren van plaatsgevonden gebeurtenissen, zoals het wijzigen van brongegevens, aan daarop geabonneerde afnemers. Deze NL GOV for CloudEvents standaard is nu in beheer bij Logius.
Voor ondersteuning van zaakgericht werken binnen gemeenten zijn API-standaarden voor zaakgericht werken ontwikkeld.

Producten
Architectuurproducten en API's

Project API referentiearchitectuur

Thema-architectuur Common Ground

Beveiligingsrichtlijnen voor API's en webservices

GEMMA standaardenlijst

API-standaardenlijst

Meer informatie
Vastgestelde standaarden op vng.nl

Overzicht gemeentelijke standaarden

Aan de slag met API-standaarden

API-specificaties (github pages)

Nederlandse API-strategie

Nederlanse API-strategie

Kennisplatform API's

Intentieovereenkomst API Strategie en Beleid

Deze pagina is het laatst bewerkt op 30 apr 2024 om 15:24.

@@ Regel 1: / Regel 1: @@
-{{Cocreatie
+Het wordt steeds belangrijker voor (applicatie)componenten om onderling goed samen te werken. Om dit mogelijk te maken kennen componenten (applicatie)services die voor andere componenten toegankelijk zijn via zogenaamde 'Application Programming Interfaces' (API's). Zo kunnen componenten op een gestructureerde manier functionaliteit van andere componenten gebruiken. Bijvoorbeeld door een API aan te bieden die voor andere componenten bruikbaar is om gegevens uit een achterliggende bronregistratie te gebruiken.
-|Cocreatiepublicatie=Cocreatie
-|GEMMAOnlinebeheerder=Beheerder Standaarden,
-}}
-[[Categorie:Berichtenstandaarden]]
-__NOTOC__
-VNG Realisatie beheert een groot deel van de gemeentelijke standaarden voor gegevens- en berichtenverkeer. Verschillende ontwikkelingen, zoals het digitaliseren van zaakgerichte processen, de Omgevingswet, nieuwe BRP, BGT en BRK, maken het vernieuwen van standaarden noodzakelijk. Ondertussen is de releaseversie van de APIs voor zaakgericht werken gepresenteerd, en wordt gewerkt aan API-standaarden voor het bevragen van basisregistraties BRP, BRK en BAG.
-===Overzicht API-standaarden voor gemeenten===
+Om doelmatig en efficiënt met API's te werken is het belangrijk om de manier waarop API's worden ontwikkeld, gedocumenteerd, getest en werken te standaardiseren. Er zijn een aantal manieren om dit te realiseren. Een daarvan is het kiezen voor een bepaalde architectuurstijl. Net als in de rest van de wereld geldt ook voor de Nederlandse overheid dat de voorkeur momenteel uitgaat naar API's die werken volgens de [https://en.wikipedia.org/wiki/Representational_state_transfer REST-architectuurstijl]. Maar dan nog geldt dat er aanvullende ontwerpkeuzes moeten worden gemaakt. Daarom is afgesproken om overheidsbrede afspraken te maken over hoe de REST-stijl wordt toegepast bij het ontwerpen van API's. Deze afspraken zijn vastgelegd in de [https://www.forumstandaardisatie.nl/open-standaarden/rest-api-design-rules REST-API Design Rules] standaard.
-{| class="wikitable"
-|-
-! API-standaard !! In beheer bij !! In ontwikkeling, 1.0-versie verwacht in !! In gebruik (versie ≥ 1.0 ) vanaf datum !! Mate van verbindendheid
-|-
-| [https://zaken-api.vng.cloud/ Zaken API] || VNG Realisatie || || 27-11-2019 ||
-|-
-| [https://catalogi-api.vng.cloud/ Catalogi API] || VNG Realisatie || || 27-11-2019 ||
-|-
-| [https://documenten-api.vng.cloud/ Documenten API] || VNG Realisatie || || 27-11-2019 ||
-|-
-| [https://besluiten-api.vng.cloud/ Besluiten API] || VNG Realisatie || || 27-11-2019 ||
-|-
-| [https://autorisaties-api.vng.cloud/ Autorisaties API] || VNG Realisatie || || 27-11-2019 ||
-|-
-| [https://notificaties-api.vng.cloud/ Notificaties API] || VNG Realisatie || || 27-11-2019 ||
-|-
-| Klanten API || VNG Realisatie || Q2 2020 || ||
-|-
-| Contactmomenten API || VNG Realisatie || Q2 2020 || ||
-|-
-| Verzoeken API || VNG Realisatie || Q2 2020 || ||
-|-
-| [https://referentielijsten-api.vng.cloud/ Referentielijsten API] (t.b.v. selectielijst) || || 2020 || ||
-|-
-| [https://github.com/VNG-Realisatie/ODS-Open-Raadsinformatie Open Raadsinformatie API] || || 2020 || ||
-|}
-In de tabel hierboven worden drie statussen onderscheiden. Deze worden hieronder toegelicht.
+Op de website [https://developer.overheid.nl developer.overheid.nl] is te zien dat er steeds meer overheids-API's beschikbaar komen die allerlei soorten functionaliteit aanbieden. Op [https://data.overheid.nl/ data.overheid.nl] worden (ook) API-specificaties gepubliceerd waarmee open data is op te vragen. Voor gemeenten zijn met name API's interessant waarmee elders vastgelegde brongegevens toegankelijk worden gemaakt. Gebruik daarvan kan bijvoorbeeld leiden tot hogere actualiteit en betrouwbaarheid van data en het onderhouden van lokale kopieën overbodig maken.
-# In ontwikkeling
-# In gebruik
-# Vastgesteld
-====In ontwikkeling====
+De [[Architectuurvisie|GEMMA Architectuurvisie]] beschrijft hoe standaardisatie via het gebruik van API's cruciaal is om toe te kunnen werken naar een fundamenteel betere informatievoorziening voor gemeenten. Iets dat verder wordt uitgewerkt binnen de [[thema-architectuur Common Ground]] die de architectuur uitwerkt die nodig is om de doelen van Common Ground te realiseren.
-API-standaarden met de status 'in ontwikkeling' kunnen gebruikt worden door gemeenten en leveranciers, maar toepassing in productiesystemen wordt niet aanbevolen. Veranderingen in specificaties die ervoor zorgen dat voorgaande versies of afhankelijke componenten niet langer werken ('breaking changes') kunnen onbeperkt en onaangekondigd worden doorgevoerd. De ontwikkelingsfase eindigt met het uitbrengen van een release candidate - een versie van de API die de voorgenomen productiespecificaties omvat waarop belanghebbende gedurende een bepaalde periode kunnen reageren.
-====In gebruik====
+Vanuit de VNG wordt op verschillende manieren gewerkt aan de ontwikkeling van gestandaardiseerde API's:
-Als een API-standaard de release cadidatefase succesvol heeft doorlopen, wordt een productieversie uitgebracht. Een API met een versienummer van 1.0 of hoger krijgt de status 'in gebruik', en is geschikt voor  gebruik in productiesystemen. API-standaarden met de status 'in gebruik' kunnen door gemeenten en leveranciers in productiesystemen worden geïmplementeerd. De in de [https://www.vngrealisatie.nl/producten/gemeentelijke-ict-kwaliteitsnormen-bij-de-gibit Gemeentelijke ICT-kwaliteitsnormen bij de GIBIT] benoemde verplichting tot implementatie van API-standaarden geldt vanaf het moment dat een API-standaard de status 'In gebruik' heeft bereikt.
-Veranderingen in specificaties die ervoor zorgen dat voorgaande versies of afhankelijke componenten niet langer werken ('breaking changes') kunnen maximaal twee keer per jaar gedurende vastgestelde releasemomenten worden doorgevoerd. Deze resulteren altijd in een nieuwe 'major release'. VNG Realisatie ondersteunt voor iedere API-standaard de meest recent uitgebrachte major release en (voor zover van toepassing) de voorafgaand uitgebrachte major release. Minor releases, die geen breaking changes omvatten kunnen onbeperkt en op ieder moment worden uitgebracht. Meer details over het releasebeleid is te vinden op [https://github.com/VNG-Realisatie/api-beheer/blob/master/versiebeheer.md GitHub-pagina over versiebeheer en releasemangement]. De hier beschreven uitgangspunten gelden alleen voor API-standaarden die door VNG Realisatie worden beheerd.
+* Via het programma HaalCentraal is gewerkt aan het ontwikkelen van de [https://vng-realisatie.github.io/Haal-Centraal/ HaalCentraal API's] zodat gemeenten beter data kunnen opvragen uit de basisregistraties.
+* Het project Notificatieservices heeft een concept-standaard ontwikkeld voor het notificeren van plaatsgevonden gebeurtenissen, zoals het wijzigen van brongegevens, aan daarop geabonneerde afnemers. Deze [https://logius.nl/domeinen/gegevensuitwisseling/nl-gov-profile-cloudevents NL GOV for CloudEvents standaard] is nu in beheer bij Logius.
+* Voor ondersteuning van zaakgericht werken binnen gemeenten zijn [https://vng.nl/projecten/zaakgericht-werken-api API-standaarden voor zaakgericht werken] ontwikkeld.
-====Mate van verbindendheid====
+{{Landingspagina
-Een verbindend verklaarde API-standaard is na een advies van het [https://vng.nl/artikelen/college-van-dienstverleningszaken College van Dienstverleningszaken] door het VNG-bestuur of de Algemene Ledenvergadering van de VNG als standaard vastgesteld. Een vaststelling kan verschillende gradaties van verbindendheid tot gevolg hebben: van 'aanbevolen deze standaard te gebruiken' tot 'verplicht deze standaard toe te passen'. In de tabel wordt per vastgestelde API-standaard aangegeven welke mate van verbindendheid geldt.
+|titel1  = Producten
+|inhoud1 =
+Architectuurproducten en API's
+* [[Project API referentiearchitectuur]]
+* [[Thema-architectuur Common Ground]]
+* [[Beveiligingsrichtlijnen voor API's en webservices]]
-Een een API-standaard met de status 'in ontwikkeling' zal op een gegevens moment vrijwel altijd de status 'in gebruik' bereiken. Deze statussen zijn opeenvolgend. Voor een verbindendverklaring geldt iets anders: die is aanvullend is bij de status 'in gebruik'. Een verbindendverklaring bepaalt alléén de mate waarin gemeenten verplicht zijn een (API-)standaard toe te passen, en beïnvloedt dus niet de geschiktheid van die API-standaard voor gebruik in productiesystemen of het releasebeleid van de standaard. De relatie tussen ontwikkeling en vaststelling van API-standaarden wordt in het diagram hieronder geïllustreerd.
+GEMMA standaardenlijst
+* [[GEMMA API-standaardenlijst|API-standaardenlijst]]
+|titel2  = Meer informatie
+|inhoud2 =
+Vastgestelde standaarden op vng.nl
+* [https://vng.nl/artikelen/overzicht-gemeentelijke-standaarden Overzicht gemeentelijke standaarden]
-[[Bestand:Ontwikkel- en vaststellingsproces API-standaarden.png|miniatuur|rechtop=1.7|Illustratie bij ontwikkeling en vaststelling van API-standaarden]]
+Aan de slag met API-standaarden
+* [https://vng-realisatie.github.io/Standaarden/API-standaarden API-specificaties (github pages)]
-===Specifieke API-standaarden===
+Nederlandse API-strategie
-====API-standaarden voor zaakgericht werken====
+* [https://docs.geostandaarden.nl/api/API-Strategie/ Nederlanse API-strategie]
-Van de APIs voor zaakgericht werken is eind 2019 een eerste productieversie (versie 1.0.0) gepresenteerd. Meer informatie over deze standaarden is te vinden op de [https://www.vngrealisatie.nl/producten/api-standaarden-zaakgericht-werken website van VNG Realisatie]. Voor ontwikkelaars is meer documentatie beschikbaar via de [https://github.com/VNG-Realisatie/gemma-zaken/releases GitHub-repository].
+* [https://www.geonovum.nl/themas/kennisplatform-apis Kennisplatform API's]
+* [https://www.geonovum.nl/themas/kennisplatform-apis/intentie-overeenkomst Intentieovereenkomst API Strategie en Beleid]
-====Haal Centraal bevragen basisregistraties====
-Onder de noemer 'Haal Centraal' wordt gewerkt aan API-definitities die het mogelijk maken om de BRP, BRK en BAG te bevragen. Meer informatie is te vinden op de Github-repository's voor [https://github.com/VNG-Realisatie/Haal-Centraal-BRP-bevragen BRP bevragen], [https://github.com/VNG-Realisatie/Haal-Centraal-BRK-bevragen BRK bevragen] en [https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen BAG bevragen].
-===Hoe komen we samen tot API-standaarden?===
+|hoogte = 350px
-Voorheen werd er toegewerkt naar één openbare consultatie waarmee een standaard eenmalig werd getoetst bij stakeholders. Bij de nieuwe werkwijze is er sprake van een voortdurende afstemming met partijen waarbij meerdere instrumenten worden ingezet, te weten:
+}}
-*Repositories op Github: te allen tijde kunnen partijen de stand van zaken raadplegen en de planning raadplegen. Ook kunnen zij bugs inschieten en wensen aanmelden in de vorm van user stories.
+{{Publicatie
-*Referentiecomponenten en API testvoorziening in de cloud waartegen getest kan worden.
+|Paginastatus=publiceren
-*Elke vier weken wordt er een publieke Sprint-demo georganiseerd waar de gerealiseerde user stories worden gedemonstreerd. Bezoekers kunnen vragen stellen en direct feedback geven op de resultaten.
+|Redactiestatus=Actueel
-*API-labs, eveneens openbaar, geven developers van gemeenten en leveranciers de kans om met ondersteuning van het ZGW team te experimenteren met de API’s. Ook hier kunnen uiteraard bugs en nieuwe wensen gemeld worden.
+|Wikibeheerder=GEMMA Beheer
-*Presentaties op de Leveranciersdag van VNG-Realisatie
+}}
+[[Category:Standaarden paginas]]
-Deze instrumenten tezamen zijn onderdeel van de openbare consultatie. Er zal dus sprake zijn van een voortdurende consultatie van de stakeholders, waarmee ook de kans ontstaat om de standaard voortdurend te verbeteren op aangeven van de gebruikers.
-‘Issues’ en ‘Pull Requests’ zijn dus meer dan welkom.
-===Problemen, suggesties en vragen===
-Het is niet nodig om software of documentatie te schrijven om toch bij te dragen. De ontwikkeling is ook gebaat bij gerapporteerde problemen, suggesties voor wijzigingen en vragen over dingen die (nog) onduidelijk zijn. Om dit te doen kan een [https://github.com/VNG-Realisatie/gemma-zaken/issues issue worden gemaakt]. Op de supportpagina’s van GitHub staat [https://help.github.com/en/articles/creating-an-issue uitleg over het maken van issues].
-====Documentatie en code====
-Maak om bij te dragen aan de documentatie of software van de ZGW API’s een zogenaamde Pull Request. Lees alles over hoe git (en GitHub) werkt in deze introductie over git flow](https://guides.github.com/introduction/flow/).
-====1. Maak je wijzigingen====
-Dit project hanteert het [https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow OneFlow branching model]. Maak je wijzigingen op een nieuwe ‘feature branch’ met de naam feature/naam-die-bijdrage-beschrijft. Zorg voor heldere beschrijvingen voor iedere commit, zodat degenen die de bijdrage moeten beoordelen een goed beeld hebben van wat de bedoeling is.
-====2. Pull Request====
-Wanneer de bijdrage compleet op de nieuwe feature branch staat kun je een Pull Request maken. Dit is, zoals de naam zegt, een verzoek aan de eigenaren van de repository om de branch met wijzigingen op te halen en in het project te voegen. Verzoek daarbij is om elke Pull Request te voorzien van een duidelijke beschrijving en eventuele issue nummers die met behulp van de Pull Request worden opgelost.
-====3. Verbeteren====
-Alle bijdragen worden beoordeeld in een review proces. Je kunt zelf ook specifiek aan een teamlid vragen om een review.
-Het kan zijn dat een Pull Request direct kan worden ingevoegd. Vaak is het echter nodig om nog het e.e.a. te verbeteren aan de Pull Request voordat deze in het project kan worden ingevoegd. Feedback op de Pull Request kan komen van de eigenaren van de standaard, van andere belanghebbenden of van geautomatiseerde tests.
-Wanneer de gewijzigde documentatie en code door de menselijke review en geautomatiseerde test komt, worden de wijzigingen van de Pull Request in het project gevoegd.
-===Status vernieuwde informatiemodellen===
-De informatiemodellen RSGB3, RGBZ2 en ImZTC2.02 zijn goedgekeurd. Toch hebben de nieuwe versies van deze standaarden de status ‘in ontwikkeling’. Zij krijgen de status ‘in gebruik’ nadat ze zijn geïmplementeerd in één of meer standaarden.
-===Wat betekent de ontwikkeling van API-standaarden voor de bestaande StUF-standaarden?===
-De ontwikkeling van StUF 03.02 en de daarmee samenhangende sectormodellen StUF BG 03.20 en StUF ZKN 03.20 is stopgezet. VNG Realisatie blijft support leveren bij de huidige generatie StUF-standaarden. Dat betekent dat we bugs, fouten en problemen herstellen.
-<!-- Page revision date: 1592549195 -->

API-standaarden: verschil tussen versies

Huidige versie van 30 apr 2024 om 15:24

Nieuws

Contact[bewerken]

Bezoekadres[bewerken]

Postadres[bewerken]