Aan deze wiki wordt momenteel gewerkt. Het kan zijn dat tijdens deze werkzaamheden links niet werken of dat sommige views niet of onvolledig getoond worden.

API-standaarden


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. Op dit moment wordt daarom onder andere gewerkt aan nieuwe standaarden voor zaakgericht werken.

Nieuwe standaarden voor zaakgericht werken

Volgens een agile proces wordt een nieuwe generatie standaarden voor zaakgericht werken ontwikkeld. Op basis van user stories worden RESTful API’s gedefinieerd die gewenste functionaliteit bieden. Tegelijkertijd ontwikkelen we referentie-implementaties, die de werking tonen en dienen als voorbeeld voor ontwikkelaars die de standaard willen implementeren.

Agile openbare consultatie

Op 18 juli wordt de Release Candidate verwacht. Vanaf dan kunnen leveranciers en gemeenten de API’s inbouwen en gaat de software over in de beheerfase. Na 18 juli 2019 kan de ZGW API standaard door leveranciers worden ingebouwd in hun producten. Tijdens de Sprint-demo’s API-Labs beoordelen en testen gemeenten en leveranciers de resultaten van de sprints en verzamelen we feedback. De laatste Demo en Sprint Reviews en API-Lab zijn gepland op:

  • donderdag 20 juni 2019, Demo en Sprint Reviews, Utrecht of Webinar livestreamen
  • dinsdag/woensdag 2&3 juli 2019, API-Lab, Utrecht
  • donderdag 18 juli 2019, Demo en Sprint Reviews, Utrecht of Webinar livestreamen

Bent u niet in staat één van de fysieke/webinar Sprint-demo’s en/of API-Lab’s bij te wonen, of heeft u aanvullende opmerkingen, dan ontvangen we uw opmerkingen, aanvullingen, suggesties graag op de consultatie-pagina

Hoe komen we samen tot API-standaarden

Standaarden kunnen we alleen samen maken. We waarderen alle suggesties, zijn blij met feedback en verwelkomen verbeteringen in dit project. Brede samenwerking leidt tot de beste standaarden.

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, t.w.:

  • 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.
  • Referentiecomponenten en API testvoorziening in de cloud waartegen getest kan worden.
  • 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.
  • 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.
  • Presentaties op de Leveranciersdag van VNG-Realisatie

Deze instrumenten tesamen 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 issue worden gemaakt. Op de supportpagina’s van GitHub staat 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 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.

Agile Scrum

Het team wat aan de ZGW API’s werkt doet dit volgens de agile scrum methodiek. Iedere sprint duurt vier weken. Gemeenten leveren user stories rond zaakgericht werken, welke vervolgens worden vertaald naar wat nodig is in de RESTful API specificatie.

Scrum boards

Er worden vier scrum boards gebruikt om de flow naar resultaat in elke sprint te faciliteren.

  • Scrum ZGW Voorbereiding Nieuwe user stories en issues komen hier op de backlog. Wanneer zij worden geprioriteerd komen ze in de flow om ze ‘ready te maken’ zodat ze opgepakt kunnen worden in de volgende sprint.
  • Scrum ZGW Realisatie Sprint x Vanuit de kolom “Ready for Sprint” worden tijdens de maandelijkse sprint planning userstories opgepakt die uitgevoerd gaan worden. Deze komen dan in de eerste kolom van het scrum board gericht op realisatie van de API specificatie.
  • Scrum ZGW Gereed Archief Op dit board is terug te vinden welke user story gereed was in welke sprint.
  • Organisatie & Impediments Op dit board bewaakt het team de voortgang van niet-inhoudelijke actiepunten en blokkades.


Review

Zowel het board Scrum ZGW Voorbereiding als Scrum ZGW Realisatie bevat een kolom voor review. Tijdens de voorbereiding worden user stories klaargemaakt om in een volgende sprint uitgevoerd te worden. Daar hoort een review bij: voldoet de user story aan de Definition of Ready? Na de realisatie vindt opnieuw een review plaats, van iedere Pull Request waarmee een wijziging of toevoeging op de standaard wordt gedaan.

Reviews worden vaak aan specifieke personen gevraagd, maar iedereen kan een review uitvoeren. Wanneer de beoordeling binnen je competenties valt, geef de review dan prioriteit boven eventuele andere bijdragen zodat iedereen zo snel mogelijk verder kan.

Status nieuwe 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 dit 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.