Beste bezoeker,

op dit moment wordt er een nieuwe release doorgevoerd op GEMMA Online. Hierdoor is de omgeving tijdelijk niet beschikbaar.

Vragen? Stuur een e-mail naar gemmaonline@vng.nl

Met vriendelijke groet, Kenniscentrum Architectuur VNG Realisatie

Ontwikkeling van de standaard

Laatst bewerkt: 21 september 2022, 15:13:14


Ontwikkeling van de standaard

  • Stap 1: Vormen werkgroep
  • Stap 2: Werkgroepactiviteiten
  • Stap 3: Release Candidate API-specificatie
  • Stap 4: Definitieve API-specificatie
  • Stap 5: Beheer


Stap 1: Vormen werkgroep

De werkgroep vormt de kern van het project om te komen tot de gewenste API-specificatie.

Samenstellen werkgroep

Aangezien het gaat om het ontwikkelen van een landelijke standaard, is de samenstelling van de werkgroep van belang. Hierbij dien je rekening te houden met een afspiegeling van relevante betrokkenen, zoals gemeenten, manifestpartijen, leveranciers, etc.
Geadviseerd wordt om voor de samenstelling van de werkgroep minimaal de volgende criteria aan te houden:

  • Voldoende deelnemers die een actieve bijdrage kunnen leveren
  • Deelnemers te zoeken welke materiedeskundig ter zake zijn en / of een expertrol hierin kunnen vervullen
  • Deelname vanuit minimaal 5 gemeenten
  • Deelname vanuit samenwerkingsverbanden
  • Deelname vanuit leveranciers
  • Deelname vanuit ketenpartners
  • Een of twee deelnemers welke de rol van werkgroepvoorzitter (aanspreekpunt) willen vervullen

Wij adviseren aan de initiatiefnemers om een GitHub repository in te richten voor online samenwerking met de werkgroep.

De ontwikkelagenda API-standaarden geeft een overzicht van alle standaardontwikkelingen met een verwijzingen naar bijbehorende GitHub repositories. Geïnteresseerden kunnen zich op GitHub aanmelden voor deelname of om op de hoogte te blijven.

Kick-off werkgroepbijeenkomst

Een kick-off werkgroepbijeenkomst wordt georganiseerd door de werkgroepvoorzitter. Tijdens deze bijeenkomst wordt het plan tot ontwikkeling doorgesproken en is er ruimte om (werk)afspraken te maken. De kick-off werkgroepbijeenkomst markeert de officiële start van de standaardontwikkeling.

Stap 2: Werkgroepactiviteiten

De werkgroep ontwerpt, ontwikkelt, beschrijft en neemt tezamen beslissingen over de in ontwikkeling zijnde API-specificatie. Dit wordt bereikt door regelmatig bij elkaar te komen om onderwerpen te bespreken en keuzes gemotiveerd vast te leggen.

Met de doelgroep van de standaard worden regelmatig reviews uitgevoerd middels community interacties. Hierdoor wordt draagvlak en (toekomstige) bruikbaarheid van de API-specificatie doorlopend getoetst. Elk project heeft een eigen verloop. De stappen om tot een API-specificatie te komen verschillen dan ook van project tot project. De werkgroep zal zelf de door haar te volgen stappen moeten plannen.

De werkgroep kan haar API-specificatie tussentijds publiceren. De werkgroep besluit daar zelfstandig toe. De API-specificatie moet daarbij voldoen aan diverse kwaliteitscriteria, zoals de landelijke API-strategie. Dit hebben we zo met elkaar afgesproken om ook de API-specificatie op een eenduidige manier te documenteren.

Tussentijdse en de definitieve API-specificatie dienen ter review uitgezet te worden aan een brede groep van belanghebbenden en geïnteresseerden, waaronder de Groeipact Common Ground deelnemers en leveranciers.

Wanneer de ontwikkelde API-specificatie door de werkgroep als voldoende volwassen wordt beschouwd om te gebruiken in implementaties, wordt deze opgeleverd als Release Candidate.

Naast de API-specificatie kan de werkgroep ook ter ondersteuning werkproducten ontwikkelen, zoals:

  • achtergrond documentatie
  • voorbeeld programmacode
  • een referentie implementatie
  • beschrijvingen van testgevallen
  • een testsuite voor het testen van implementaties
  • een Quick Start Guide


Stap 3: Release Candidate API-specificatie

De Release Candidate van de API-specificatie wordt als voldoende volwassen beschouwd en is gereed om te gebruiken in implementaties. Partijen die implementaties van de API-specificatie ontwikkelen kunnen gedurende de Release Candidate fase hun bevindingen terugkoppelen aan de werkgroep. Deze bevindingen kunnen leiden tot een nieuwe Release Candidate, of worden meegenomen in de definitieve versie van de API-specificatie.

Stap 4: Definitieve API-specificatie

De API-specificatie welke door de werkgroep wordt beschouwd als voldoende beproefd, wordt als definitieve API-specificatie beschikbaar gesteld in de GitHub repository, met alle relevante verwijzingen naar ondersteunende werkproducten. Na oplevering van de definitieve API-specificatie is het project voltooid en kan deze overgaan naar een beheerpartij en houdt de werkgroep op met bestaan.

Indien gewenst kan de API-specificatie de formele status van API-standaard krijgen en worden aangemerkt als ‘aanbevolen’, ‘pas toe of leg uit’ of ‘verplicht te gebruiken’. Hiervoor kun je het proces standaardverklaring doorlopen.


Zie Proces Standaardverklaring

Stap 5: Beheer

Beheer van een API-specificatie waarborgt het beschikbaar blijven van alle artefacten en het onderhoud daarvan, nadat deze is ontwikkeld. Voor een API-specificatie in beheer betreft dat:

  • het beschikbaar houden van toegang tot alle artefacten
  • het vastleggen van gemelde problemen
  • het oplossen van kleine problemen
  • het opnieuw uitgeven van de door beheer aangepaste API-specificatie
  • het vastleggen van nieuwe wensen tot uitbreiding of aanpassing, welke mogelijk in de toekomst kunnen worden opgepakt bij doorontwikkelingen

Wat minimaal nodig is voor beheer van een API-specificatie is hier beschreven.