VNG compliancy

The Objects and Objecttypes API specifications are proposed by the municipality of Utrecht and submitted to the VNG for to become a Dutch national standard. The VNG (Vereniging van Nederlandse Gemeenten) is the Association of Dutch Municipalities.

The VNG has drafted an initial checklist for new API standards which is shown in the table below. The table below also shows the compliancy to this checklist for both APIs. This checklist is only available in Dutch.

1. Stakeholder documentatie

#

Description

Answer

Remarks

1

De voor de stakeholders relevante onderdelen van de standaard (informatiemodel, API-specificaties, functionele specificatie, architectuurmodellen, referentieimplementatie(s) en testgevallen) zijn gepubliceerd op de VNG Realisatie Github of GEMMAonline omgeving.

No 1

2

Er is een beschrijving die ontwikkelaars op weg helpt om te starten met implementatie van de API-standaard.

Yes

3

Er is uitleg en installatie-instructies van de referentieimplementaties

Yes

4

Er is uitleg over hoe mee ontwikkeld kan worden aan de referentieimplementatie(s), inclusief gebruik van relevante tooling.

Yes

5

Er zijn Postman-scripts met voorbeelden zodat consumers snel kunnen leren hoe ze de API moeten aanroepen.

Yes

6

VNG-site, API-ontwikkelagenda

Yes

No link available.

2. Informatiemodel

#

Description

Answer

Remarks

1

Indien gemeentelijke bron dan opleveren informatiemodel (semantisch informatiemodel)

Yes

2

Altijd een uitwisselingsgegevensmodel

No

3

Modellering van het semantisch informatiemodel conform laatst vastgestelde versie Metamodel Informatiemodellen (MIM)

Yes

See 2.1.

4

Informatiemodel gemodelleerd in Enterprise Architect conform de daarvoor geldende best practices

Yes

See 2.1.

5

Informatiemodel is opgeslagen in SVN

No 1

3. Architectuur

#

Description

Answer

Remarks

1

Modellen zijn gemodelleerd in Archi (Archimate 3.x) conform conventies GEMMA

No

Unclear

2

Modellen zijn opgeslagen op GitLab / Github en ingericht voor samenwerking (main/develop branches)

No

3

De stakeholders van de API-standaard zijn beschreven

Yes

4

Interactiepatronen zijn gemodelleerd

Yes

5

Positie van de API-standaard in de GEMMA informatiearchitectuur is gemodelleerd

No

Unclear

6

Verwacht gedrag van een API is gemodelleerd als applicatieproces

No

Unclear

7

De referentiecomponenten die het koppelvlak moeten realiseren zijn beschreven

Yes

8

Per referentiecomponent is beschreven welke verplicht dan wel optioneel te leveren (provider) of te gebruiken (consumer) services en operaties geïmplementeerd moeten zijn om compliant aan de standaard te zijn.

Yes

4. API-specificaties

#

Description

Answer

Remarks

1

Opgesteld in Open API Specification 3.x

Yes

2

Gepubliceerd op VNG-Realisatie Github omgeving en beschikbaar via Redoc en Swagger

No 1

3

Ontwerpbeslissing zijn vertaald naar (aanvullende) specificaties

Yes

4

Voldoet aan landelijke API strategie, in het bijzonder de core design rules

Yes

5

Informatiebeveiliging en privacy best practices (IBD) worden gevolgd

No

Unclear

6

Aanvullende specificaties die het gedrag van de API specificeren voor de provider.

No

TODO

7

De OAS3-specificatie is getest voor toepasbaarheid in de mainstream code-generatoren

Yes (1, 2)

8

API-specificaties volgen de VNG-R best practices.

No

There are no VNG-R best practices.

5. Compliancy en testen

#

Description

Answer

Remarks

1

API-standaard is geïmplementeerd in een referentieimplementatie indien voor de standaard meerdere providers van toepassing kunnen zijn

Yes (1, 2)

2

Testgevallen zijn beschreven voor elke service/operatie en aanvullende specificaties, zowel voor de happy als de unhappy flows

Yes (1, 2)

3

Elk testgeval beschrijft het logische testgeval, de teststap(pen) (wat wordt gedaan) en het verwachte resultaat

No

Unclear

4

Er zijn compliancy tests beschikbaar voor elke referentie-component (consumers en providers) en alle betreffende services en operaties, zodat leveranciers kunnen testen en aantonen dat hun applicatie voldoet aan de standaard

No

TODO

5

Voor zover nodig is ook de testdata beschreven die wordt gebruikt in de testgevallen

No

See 5.4.

6

Testgevallen zijn geïmplementeerd als Postman-scripts zodat de API geautomatiseerd getest kan worden.

No

See 5.4.

7

Postman-scripts zijn gepubliceerd op api-test.nl zodat iedereen kan testen of de API voldoet aan zijn specificatie.

No

See 5.4.

6. Referentie-implementatie

#

Description

Answer

Remarks

1

Zowel consumer als provider implementatie. Provider alleen van toepassing als meerdere providers mogelijk zijn. Minimaal zorgen voor test-implementatie

Yes (1, 2)

Same as 5.1.

2

Implementeert de OAS-specificatie inclusief de eventueel gedefinieerde aanvullende specificatie

Yes

Unsure how to provide proof.

3

Is voldoende functioneel om implementatie en gebruik van de API-standaard te demonstreren en compliancy aan te tonen

Yes

Unsure how to provide proof.

7. Overdrachtsdocument (beheer)

#

Description

Answer

Remarks

1

De genomen ontwerpbeslissingen zijn beschreven en gemotiveerd

Yes

2

Er is een lijst met bekende fouten, gewenste verbeteringen, gewenste uitbreidingen (backlog)

Yes

3

Er wordt voldaan aan de acceptatie criteria van de beheer organisatie die de standaard in beheer neemt

Yes

This checklist.

4

Beheerafspraken zijn beschreven

No

Unclear

1(1,2,3)

This is most likely an internal VNG compliancy check and is considered out of scope.