API-standaarden: verschil tussen versies

Geen bewerkingssamenvatting
Geen bewerkingssamenvatting
 
(29 tussenliggende versies door 2 gebruikers niet weergegeven)
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. Ontwikkelingen, als het digitaliseren van zaakgerichte processen, de Omgevingswet, het sociaal domein en het vernieuwen van de ontsluiting van basisregistraties maken het vernieuwen van standaarden noodzakelijk. Sinds 2019 werken gemeenten, ketenpartners, VNG en marktpartijen aan het realiseren van API-standaarden.


De Community API-standaarden is in oprichting en werkt aan een nieuw raamwerk standaardisatie gegevensuitwisseling. Dit raamwerk beschrijft hoe we samen zo lean mogelijk het proces van standaardisatie organiseren terwijl ondertussen werkgroepen doorontwikkelen binnen de kaders. Hierbij alvast een voorbeeld van een raamwerk dat vormgegeven zal worden <br/>
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.
<imagemap>
Bestand:Raamwerk_standaardisatie_v2.jpg|800px
</imagemap>


==Status van API-standaarden voor gemeenten==
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.  
Er zijn inmiddels al standaard API-specificaties op de pas toe leg uit lijst geplaatst. Het complete overzicht van alle API-standaarden is te vinden op [https://gemmaonline.nl/index.php/Ontwikkelagenda_API-standaarden de API-ontwikkelagenda]. Hieronder staat de fasering van API's uitgelegd en onderaan deze pagina vind je de status van de formeel goedgekeurde API-standaarden..


===Idee===
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.  
Zeer prille fase, idee wordt ergens gevormd in gemeente of keten. Idee kan ook als een onderwerp top down wordt ingebracht, bijvoorbeeld wetgeving.
Geen/amper capaciteit aan besteed, nog geen inschatting van kosten en capaciteit.


===Analyse===
Vanuit de VNG wordt op verschillende manieren gewerkt aan de ontwikkeling van gestandaardiseerde API's:
Initiatiefnemers doen onderzoek naar wat het in houdt en om goedkeuring te krijgen. Verschillende oplossingsrichtingen worden uitgewerkt en een architectuurtoets wordt uitgevoerd. Er wordt een inschatting (eventueel met eerste impactanalyse) gemaakt. Als product van deze fase een verkorte zakelijke rechtvaardiging. Het item heeft een eerste inschatting van kosten en capaciteit.


===Prioritering===
* 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.  
Na de analyse is het initiatief toegevoegd aan de backlog van alle goedgekeurde ideeen en alles wat al loopt. In deze fase worden de initiatieven ten opzichte van elkaar gewogen aan de hand van wegingsfactoren. Als een initiatief hoog wordt geprioriteerd, dan komt deze op de backlog (let op, dit is nog niet ingepland!). Als een initiatief laag wordt geprioriteerd, dan blijft deze op de roadmap.
* 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.


===Realisatie===
{{Landingspagina
De initiatieven op de backlog worden in uitvoering genomen.
|titel1  = Producten
De standaard wordt ontworpen, óf een in ontwikkeling zijnde API wordt tot standaard geadopteerd, conform het adoptieproces. Eerste stap is een architectuurconcept en informatiemodel.
|inhoud1 =  
API-standaarden met de status ‘realisatie' 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.
Architectuurproducten en API's
* [[Project API referentiearchitectuur]]
* [[Thema-architectuur Common Ground]]
* [[Beveiligingsrichtlijnen voor API's en webservices]]


===Release Kandidaat===
GEMMA standaardenlijst
De realisatiefase eindigt met het uitbrengen van een release kandidaat - een versie van de API die de voorgenomen productiespecificaties omvat waarop belanghebbende gedurende een bepaalde periode kunnen reageren
* [[GEMMA API-standaardenlijst|API-standaardenlijst]]
|titel2  = Meer informatie
|inhoud2 =  
Vastgestelde standaarden op vng.nl
* [https://vng.nl/artikelen/overzicht-gemeentelijke-standaarden Overzicht gemeentelijke standaarden]


===Implementeerbaar===
Aan de slag met API-standaarden
Als een API-standaard de vorige fase succesvol heeft doorlopen, wordt een productieversie uitgebracht. Een API met een versienummer van 1.0 of hoger krijgt de status ‘implementeerbaar', en is geschikt voor gebruik in productiesystemen. API-standaarden met de status ‘implementeerbaar' kunnen door gemeenten en leveranciers in productiesystemen worden geïmplementeerd. De in de Gemeentelijke ICT-kwaliteitsnormen bij de GIBIT benoemde verplichting tot implementatie van API-standaarden geldt vanaf het moment dat een API-standaard de status ‘Implementeerbaar' heeft bereikt.
* [https://vng-realisatie.github.io/Standaarden/API-standaarden API-specificaties (github pages)]
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 GitHub-pagina over versiebeheer en releasemangement. De hier beschreven uitgangspunten gelden alleen voor API-standaarden die door VNG Realisatie worden beheerd.


=== Verbindend verklaard===
Nederlandse API-strategie
Een verbindend verklaarde API-standaard is na een advies van het 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.
* [https://docs.geostandaarden.nl/api/API-Strategie/ Nederlanse API-strategie]
Een API-standaard met de status realisatie' zal op een gegevens moment vrijwel altijd de status ‘implementeerbaar' bereiken. Deze statussen zijn opeenvolgend. Voor een verbindendverklaring geldt iets anders: die is aanvullend is bij de status ‘implementeerbaar'. 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.  
* [https://www.geonovum.nl/themas/kennisplatform-apis Kennisplatform API's]
* [https://www.geonovum.nl/themas/kennisplatform-apis/intentie-overeenkomst Intentieovereenkomst API Strategie en Beleid]


==Welke standaarden zijn in gebruik?==
{| class="wikitable"
! API-standaard !! In beheer bij !! In ontwikkeling <small>- 1.0-versie verwacht in</small> !! In gebruik (versie ≥ 1.0 ) <small>vanaf datum</small> !! Mate van verbindendheid
|-
|- bgcolor="#f4c8d5"
|colspan="5" |''Onderdeel van API-standaarden voor Zaakgericht Werken''
|-
| bgcolor="#f6e9fe" | [https://zaken-api.vng.cloud/ Zaken API] || VNG Realisatie || || 27-11-2019 || pas toe leg uit
|-
| bgcolor="#f6e9fe" | [https://catalogi-api.vng.cloud/ Catalogi API] || VNG Realisatie || || 27-11-2019 || pas toe leg uit
|-
| bgcolor="#f6e9fe" |  [https://documenten-api.vng.cloud/ Documenten API] || VNG Realisatie || || 27-11-2019 || pas toe leg uit
|-
| bgcolor="#f6e9fe" | [https://besluiten-api.vng.cloud/ Besluiten API] || VNG Realisatie || || 27-11-2019 || pas toe leg uit
|-
| bgcolor="#f6e9fe" | [https://autorisaties-api.vng.cloud/ Autorisaties API] || VNG Realisatie || || 27-11-2019 || pas toe leg uit
|-
| bgcolor="#f6e9fe" | [https://notificaties-api.vng.cloud/ Notificaties API] || VNG Realisatie || || 27-11-2019 || pas toe leg uit
|-
|- bgcolor="#c4e5d6"
|colspan="5" | ''Onderdeel van Haal Centraal''
|-
| bgcolor="#effafe" | [https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/ BAG Bevragen API] || || || 13-8-2020 || nader te bepalen
|-
| bgcolor="#effafe" | [https://github.com/VNG-Realisatie/Haal-Centraal-BRK-bevragen/ BRK Bevragen API] || || || 3-6-2020 || nader te bepalen
|-
| bgcolor="#effafe" | [https://github.com/VNG-Realisatie/Haal-Centraal-BRP-bevragen/ BRP Bevragen API] || || || 01-10-2020 || nader te bepalen
|-


|}
|hoogte = 350px
 
}}
==Hoe komen we samen tot API-standaarden?==
{{Publicatie
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:
|Paginastatus=publiceren
*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.
|Redactiestatus=Actueel
*Referentiecomponenten en API testvoorziening in de cloud waartegen getest kan worden.
|Wikibeheerder=GEMMA Beheer
*Presentaties op de Leveranciersdag van VNG-Realisatie.
}}
*Fieldlabs waar in sessies de toekomstige behoeften in kaart gebracht worden.
[[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].
 
===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.
In 2021 werken we aan de transitieplan om tot uitfasering van StUF te komen.
<!-- Page revision date: 1612472319 -->

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

GEMMA standaardenlijst

Meer informatie
Vastgestelde standaarden op vng.nl

Aan de slag met API-standaarden

Nederlandse API-strategie

Een computerprogramma om een specifieke taak uit te voeren die geen betrekking heeft op de werking van de computer zelf.

Afkorting van 'application programming interface': een manier om twee of meer computerprogramma's met elkaar te laten communiceren. Het is een soort software-interface die een dienst aanbiedt aan andere stukjes software.

Een meervoudig te gebruiken registratie met betrouwbare data

Afkorting voor de Representational State Transfer architectuurstijl voor gedistribueerde hypermedia systemen

Een document met erkende afspraken, specificaties of criteria over een product, een dienst of een methode.

Weergave van een feit, begrip of aanwijzing, geschikt voor overdracht, interpretatie of verwerking door een persoon of apparaat.

De mate waarin de organisatie zich voor de informatievoorziening kan verlaten op een informatiesysteem. De betrouwbaarheid van een informatiesysteem is daarmee de verzamelterm voor de begrippen beschikbaarheid, integriteit en vertrouwelijkheid.

Het opleggen van een bepaalde norm of standaard voor het ontwerp, de constructie, het testen of gebruiken van een product of proces.

Het geheel van mensen, middelen en maatregelen, gericht op de informatiebehoefte van de organisatie.

De fundamentele concepten of eigenschappen van een systeem in zijn omgeving belichaamd in zijn elementen, relaties en in de principes van zijn ontwerp en evolutie.

Normatieve en descriptieve documenten die huidige/toekomstige architectuur van een organisatie/domein schetsen.

De GEMeentelijke ModelArchitectuur met een verzameling samenhangende kaders, richtlijnen, referentiemodellen en standaarden die gemeenten helpt bij het inrichten van hun IT-omgeving en processen.

Betekenisvolle gegevens.

Overgenomen van "https://www.gemmaonline.nl/index.php?title=API-standaarden&oldid=1062607"
Deze pagina is het laatst bewerkt op 30 apr 2024 om 15:24.