Normen en conformiteit
De Avallo REST API is ontworpen aan de hand van vastgelegde standaarden en ontwerpregels.
Deze sectie beschrijft tegen welke norm en versie de API is beoordeeld, hoe de beoordeling tot stand komt en waar regels niet van toepassing zijn of een aanvullende handmatige onderbouwing vereisen.
Een conformiteitsbeoordeling geldt uitsluitend voor de expliciet genoemde norm en versie.
NLGov REST API Design Rules
Section titled “NLGov REST API Design Rules”De huidige API is beoordeeld tegen:
NLGov REST API Design Rules 2.2.0De beoordeling is gekoppeld aan versie 2.2.0. Een nieuwere versie van de ontwerpregels wordt pas onderdeel van de beoordeling nadat deze afzonderlijk is onderzocht en geadopteerd.
Betekenis van conformiteit
Section titled “Betekenis van conformiteit”Niet iedere ontwerpregel is noodzakelijk van toepassing op iedere API.
Iedere regel krijgt daarom afzonderlijk een status:
| Status | Betekenis |
|---|---|
| Voldoet | De API voldoet aantoonbaar aan de regel. |
| Voldoet gedeeltelijk | De regel is technisch geïmplementeerd, maar vraagt nog aanvullende inhoudelijke of organisatorische onderbouwing. |
| Niet van toepassing | De regel is niet relevant voor het huidige API-contract. |
| Wijkt af | De API wijkt bewust van de regel af. De reden en gevolgen worden vastgelegd. |
| Nog niet beoordeeld | Er is nog onvoldoende bewijs voor een onderbouwde beoordeling. |
De status Voldoet wordt alleen gebruikt wanneer dit kan worden onderbouwd met het OpenAPI-contract, de implementatie, geautomatiseerde tests, linting, handmatige beoordeling of een combinatie daarvan.
Reikwijdte
Section titled “Reikwijdte”De beoordeling heeft betrekking op de publiek beschikbare Avallo REST API onder:
https://api.avallo.nl/v1Binnen de reikwijdte vallen het publieke HTTP-contract, request- en responsemodellen, authenticatie, autorisatie, foutafhandeling, versiebeheer, transportvoorwaarden en de bijbehorende documentatie.
Interne componenten, beheerinterfaces, niet-publieke endpoints en systemen van afnemers vallen buiten deze beoordeling, tenzij dit op een detailpagina expliciet anders is vermeld.
Beoordelingsmethode
Section titled “Beoordelingsmethode”Technische regels worden waar mogelijk geautomatiseerd gecontroleerd.
De releasecontrole bestaat onder andere uit:
- runtime conformance-tests voor de publieke endpoints;
- validatie van het gegenereerde OpenAPI-document;
- Spectral-linting tegen de vastgelegde NLGov ruleset 2.2.0;
- expliciete classificatie van de toepasselijkheid van normatieve modules.
Regels die inhoudelijke of organisatorische interpretatie vereisen blijven daarnaast onderdeel van een handmatige beoordeling.
Een geslaagde geautomatiseerde controle is daarom sterk bewijs voor technische conformiteit, maar geen onafhankelijke certificering.
Bewijs en herleidbaarheid
Section titled “Bewijs en herleidbaarheid”Iedere status moet herleidbaar zijn naar passend bewijs.
Dit kan een onderdeel van het OpenAPI-document, een testresultaat, een documentatiepagina, een ontwerpbesluit of een vastgelegde afwijking zijn.
De detailpagina van een norm beschrijft per regel of regelgroep de status, de implementatie en eventuele beperkingen.
Afwijkingen en uitzonderingen
Section titled “Afwijkingen en uitzonderingen”Wanneer een automatische regel niet passend is op het domein, wordt een uitzondering alleen toegepast wanneer deze expliciet is vastgelegd en gemotiveerd.
De huidige Spectral-configuratie bevat een gerichte uitzondering voor verticalDatum: een verticaal datum is een geodetisch hoogtereferentiestelsel en geen kalenderdatum.
Geen certificering
Section titled “Geen certificering”Deze documentatie is een transparante beoordeling van het publieke API-contract.
Het is geen onafhankelijke certificering en geen verklaring van een toezichthouder of certificerende instelling.
Beschikbare beoordelingen
Section titled “Beschikbare beoordelingen”De huidige beoordeling is beschikbaar op:
Herbeoordeling
Section titled “Herbeoordeling”De conformiteitsbeoordeling wordt opnieuw uitgevoerd wanneer het publieke API-contract wezenlijk verandert, een nieuwe hoofdversie wordt gepubliceerd of Avallo een nieuwe versie van de ontwerpregels adopteert.
Ook nieuwe bevindingen uit tests, linting of handmatige beoordeling kunnen aanleiding zijn om een eerdere status te wijzigen.
De gebruikte normversie en beoordelingsdatum worden op de detailpagina vastgelegd.