NLGov REST API Design Rules 2.2.0
De Avallo REST API is beoordeeld tegen de NLGov REST API Design Rules 2.2.0.
Deze pagina legt per relevante ontwerpregel vast of de regel van toepassing is, wat de huidige conformiteitsstatus is en waarop die beoordeling is gebaseerd.
Beoordelingsgegevens
Section titled “Beoordelingsgegevens”| Eigenschap | Waarde |
|---|---|
| Norm | NLGov REST API Design Rules |
| Normversie | 2.2.0 |
| API | Avallo REST API |
| API-hoofdversie | v1 |
| API-contractversie | 1.0.0 |
| OpenAPI-versie | 3.1.1 |
| Beoordelingsdatum | 2026-09-10 |
| Beoordelingsstatus | Releasebeoordeling |
Samenvatting
Section titled “Samenvatting”De huidige publieke API wordt geautomatiseerd gecontroleerd met runtime conformance-tests en met Spectral tegen de vastgelegde NLGov ruleset 2.2.0.
De technische controles omvatten onder andere resourceclassificatie, pad- en querynaamgeving, HTTP-methoden, statuscodes, Problem Details, datum- en tijdnotatie, UTC-normalisatie, OpenAPI-publicatie en validatie, versieheaders, TLS-voorwaarden, security headers, CORS, statelessness, validatiefouten, versiebeheer, changelogpublicatie en de toepasselijkheid van normatieve modules.
De geautomatiseerde controles slagen voor het huidige releasecontract.
Twee onderwerpen blijven als inhoudelijke documentatiebeoordeling gedeeltelijk conform: de formele onderbouwing van de gebruikte Engelse interfaceterminologie en de taalkeuze van het OpenAPI-document. Dit zijn geen bekende technische afwijkingen in de API-uitvoering.
Gebruikte statussen
Section titled “Gebruikte statussen”| Status | Betekenis |
|---|---|
| Voldoet | De implementatie of het gepubliceerde contract voldoet aantoonbaar aan de regel. |
| Voldoet gedeeltelijk | De technische implementatie is passend, maar aanvullende inhoudelijke onderbouwing blijft gewenst. |
| Niet van toepassing | De regel is niet relevant voor de huidige functionaliteit van de API. |
| Wijkt af | De API wijkt bewust van de regel af. |
| Nog niet beoordeeld | Er is nog onvoldoende bewijs om een status vast te stellen. |
Resources en naamgeving
Section titled “Resources en naamgeving”/core/no-trailing-slash
Section titled “/core/no-trailing-slash”Status: Voldoet
De publieke resourcepaden worden zonder afsluitende slash aangeboden:
/groundwater-monitoring-wells/groundwater-monitoring-tubes/{tubeIdentifier}/measurementsRequests met een trailing slash worden niet stilzwijgend geaccepteerd of omgeleid.
/core/path-segments-kebab-case
Section titled “/core/path-segments-kebab-case”Status: Voldoet
Samengestelde padsegmenten gebruiken kebab-case:
groundwater-monitoring-wellsgroundwater-monitoring-tubesmeasurements/core/query-keys-camel-case
Section titled “/core/query-keys-camel-case”Status: Voldoet
De measurements-resource gebruikt:
fromtoBeide querykeys voldoen aan camelCase.
/core/naming-resources
Section titled “/core/naming-resources”Status: Voldoet
De publieke paden beschrijven resources met zelfstandige naamwoorden:
groundwater-monitoring-wellsgroundwater-monitoring-tubesmeasurementsDe paden bevatten geen werkwoorden waarmee RPC-bewerkingen worden gemodelleerd.
/core/naming-collections
Section titled “/core/naming-collections”Status: Voldoet
Collectieresources gebruiken meervoudsvormen:
groundwater-monitoring-wellsgroundwater-monitoring-tubesmeasurements/core/interface-language
Section titled “/core/interface-language”Status: Voldoet gedeeltelijk
De publieke interface gebruikt Engelse domeinterminologie, waaronder:
groundwater-monitoring-wellsgroundwater-monitoring-tubesmeasurementstubeIdentifierobservedAtverticalDatumDe terminologie is inhoudelijk consistent binnen het publieke contract. Voor een volledige formele onderbouwing blijft het wenselijk vast te leggen op welke officiële of gezaghebbende Engelse terminologie de gekozen begrippen zijn gebaseerd.
/core/hide-implementation
Section titled “/core/hide-implementation”Status: Voldoet
Het publieke contract beschrijft domeinresources en stelt geen interne implementatiedetails beschikbaar.
Geautomatiseerde controles bewaken onder andere dat het OpenAPI-document en responseheaders geen CLR-namespaces, frameworknamen, serverimplementatie of interne details publiceren.
Datum en tijd
Section titled “Datum en tijd”/core/date-time/format
Section titled “/core/date-time/format”Status: Voldoet
De velden en parameters die een tijdstip vertegenwoordigen gebruiken OpenAPI date-time.
Dit geldt voor:
fromtoobservedAt/core/date-time/date-omit-time-portion
Section titled “/core/date-time/date-omit-time-portion”Status: Niet van toepassing
De huidige API bevat geen publieke velden die uitsluitend een kalenderdatum vertegenwoordigen.
/core/date-time/timezone
Section titled “/core/date-time/timezone”Status: Voldoet
from en to gebruiken DateTimeOffset-semantiek. Een client mag een geldige tijdzone-offset meesturen.
Bijvoorbeeld:
2026-09-10T10:00:00+02:00De API normaliseert tijdstippen naar UTC en retourneert bijvoorbeeld:
2026-09-10T08:00:00ZGeautomatiseerde tests controleren zowel geldige offsets als de UTC-notatie van geretourneerde tijdstippen.
/core/http-methods
Section titled “/core/http-methods”Status: Voldoet
De huidige publieke resources gebruiken:
GETDe gebruikte methoden worden zowel in routing, OpenAPI als runtime gecontroleerd.
/core/http-safety
Section titled “/core/http-safety”Status: Voldoet
De publieke GET-operations lezen gegevens en wijzigen geen resources.
Geautomatiseerde tests controleren dat herhaalde uitvoering geen observeerbare resourcestatus wijzigt.
/core/http-response-code
Section titled “/core/http-response-code”Status: Voldoet
Het publieke contract documenteert passende HTTP-statuscodes:
| Statuscode | Toepassing |
|---|---|
200 | Succesvolle verwerking |
400 | Ongeldige of ontbrekende invoer |
401 | Ontbrekende of ongeldige authenticatie |
403 | Request geweigerd door een beveiligings- of transportvoorwaarde |
404 | URI of peilbuis niet beschikbaar |
405 | HTTP-methode niet ondersteund |
429 | Verzoeklimiet bereikt |
500 | Onverwachte serverfout |
Voor endpoints met pathparameters en rate limiting wordt ook gecontroleerd dat de relevante foutstatuscodes in OpenAPI zijn gedocumenteerd.
/core/stateless
Section titled “/core/stateless”Status: Voldoet
De API gebruikt geen server-side sessiestore voor de publieke endpoints.
De conformance-tests controleren daarnaast dat een eerste request op een nieuwe applicatie-instantie zonder voorafgaande requests kan worden uitgevoerd en dat geen sessiecookie wordt aangemaakt.
Relaties en bewerkingen
Section titled “Relaties en bewerkingen”/core/nested-child
Section titled “/core/nested-child”Status: Voldoet
groundwater-monitoring-wells is een zelfstandige collection resource voor discovery.
De measurements-resource wordt benaderd binnen de context van een concrete peilbuis:
/groundwater-monitoring-tubes/{tubeIdentifier}/measurementstubeIdentifier is daarmee de ancestor routeparameter van de onderliggende measurements-resource.
/core/resource-operations
Section titled “/core/resource-operations”Status: Niet van toepassing
De huidige API bevat geen resourcespecifieke commands die als werkwoord in het pad zijn gemodelleerd.
Er zijn geen publieke paden zoals:
/calculate/validate/export/executeFoutafhandeling
Section titled “Foutafhandeling”/core/error-handling/problem-details
Section titled “/core/error-handling/problem-details”Status: Voldoet
Foutresponses gebruiken:
application/problem+jsonHet publieke contract gebruikt de standaard Problem Details-velden:
typetitlestatusdetailinstanceGeautomatiseerde tests controleren Problem Details onder andere voor 400, 401, 404 en 405.
/core/error-handling/invalid-input
Section titled “/core/error-handling/invalid-input”Status: Voldoet
Ongeldige of ontbrekende invoer wordt afgehandeld met:
400 Bad RequestVoor modelvalidatie wordt ValidationProblemDetails gebruikt.
/core/error-handling/all-errors
Section titled “/core/error-handling/all-errors”Status: Voldoet
Wanneer meerdere verplichte queryparameters tegelijk ontbreken, worden de bijbehorende validatiefouten gezamenlijk in het errors-object geretourneerd.
De conformance-suite controleert dit gedrag runtime.
Documentatie
Section titled “Documentatie”/core/doc-openapi
Section titled “/core/doc-openapi”Status: Voldoet
De API publiceert een geldig OpenAPI-document met:
OpenAPI 3.1.1Het document wordt door de testset geparsed en gevalideerd en bevat de conforming endpoints, schemas, parameters, responses, authenticatie, serverinformatie en contactgegevens.
Daarnaast wordt het document met Spectral gecontroleerd tegen de NLGov REST API Design Rules 2.2.0.
Spectral-uitzondering voor verticalDatum
Section titled “Spectral-uitzondering voor verticalDatum”De Spectral-configuratie bevat één gerichte uitzondering voor de regel:
nlgov:specify-format-for-date-and-timeop:
components.schemas.GroundwaterLevelSeries.properties.verticalDatumDe reden is dat verticalDatum een geodetisch hoogtereferentiestelsel beschrijft, zoals NAP, en geen kalenderdatum of tijdwaarde.
/core/doc-openapi-contact
Section titled “/core/doc-openapi-contact”Status: Voldoet
Het OpenAPI-document bevat een contact-object met:
nameurlemail/core/doc-language
Section titled “/core/doc-language”Status: Voldoet gedeeltelijk
De primaire gebruikersdocumentatie wordt in het Nederlands gepubliceerd.
Het publieke OpenAPI-contract gebruikt Engelstalige namen en beschrijvingen. De terminologie is consistent, maar voor volledige formele conformiteit blijft dezelfde inhoudelijke onderbouwing van de Engelse terminologie nodig als bij /core/interface-language.
/core/publish-openapi
Section titled “/core/publish-openapi”Status: Voldoet
Het OpenAPI-document is zonder API-sleutel beschikbaar op:
https://api.avallo.nl/v1/openapi.jsonGeautomatiseerde tests controleren dat de JSON-variant publiek leesbaar, parseerbaar en minimaal OpenAPI 3 is. Voor het publieke OpenAPI-document wordt cross-origin uitlezen toegestaan.
Versiebeheer
Section titled “Versiebeheer”/core/deprecation-schedule
Section titled “/core/deprecation-schedule”Status: Niet van toepassing
Er wordt momenteel geen endpoint, functionaliteit of API-versie uitgefaseerd.
De huidige endpoints zijn expliciet als niet-verouderd geclassificeerd.
/core/transition-period
Section titled “/core/transition-period”Status: Niet van toepassing
v1 is de eerste hoofdversie en er is geen opvolgende hoofdversie in overgang.
De major-version lifecycle is expliciet als initiële hoofdversie vastgelegd en wordt tegen de OpenAPI-versie gecontroleerd.
/core/changelog
Section titled “/core/changelog”Status: Voldoet
Voor API-versie 1.0.0 is een publiek wijzigingsoverzicht vastgelegd.
De conformance-suite controleert dat de changeloglocatie een publieke HTTPS-URI is en dat de huidige OpenAPI-versie in de gepubliceerde versiecollectie voorkomt.
/core/uri-version
Section titled “/core/uri-version”Status: Voldoet
De hoofdversie is opgenomen in het basispad:
https://api.avallo.nl/v1Alle publieke conforming endpoints bevinden zich onder dezelfde major-versie.
/core/semver
Section titled “/core/semver”Status: Voldoet
Het OpenAPI-document vermeldt:
1.0.0Deze waarde wordt geautomatiseerd gevalideerd tegen Semantic Versioning 2.0.0.
/core/version-header
Section titled “/core/version-header”Status: Voldoet
Door de API gegenereerde responses bevatten:
API-Version: 1.0.0De testset controleert de header op succesvolle responses en op onder andere 401, 404 en 405. Daarnaast wordt gecontroleerd dat de header voor de gedocumenteerde responses in OpenAPI is opgenomen.
Transportbeveiliging
Section titled “Transportbeveiliging”/core/transport/tls
Section titled “/core/transport/tls”Status: Voldoet
De publieke API accepteert alleen requests die vanuit de vertrouwde ingress als versleuteld en met toegestane TLS-eigenschappen zijn doorgegeven.
De conformance-suite controleert dat requests worden geweigerd wanneer transportmetadata ontbreekt of wanneer onder andere een onversleutelde verbinding, verouderde TLS-versie, niet-toegestane cipher suite of ongeldige combinatie wordt gemeld.
Deze controle geldt binnen de vastgelegde trust boundary tussen publieke ingress en applicatie.
/core/transport/no-sensitive-uris
Section titled “/core/transport/no-sensitive-uris”Status: Voldoet
Authenticatiegegevens worden uitsluitend via de header verstuurd:
X-API-Key: {apiKey}De API-sleutel staat niet in het pad of de querystring.
Voor de huidige endpoints zijn de URI-parameters expliciet beoordeeld. tubeIdentifier is een opaque resourceidentifier zonder persoonsgegevens, locatiegegevens of credentials. from en to bevatten uitsluitend het gevraagde tijdsinterval.
/core/transport/security-headers
Section titled “/core/transport/security-headers”Status: Voldoet
De conformance-tests controleren de beveiligingsheaders op succesvolle en foutresponses.
De gecontroleerde headers zijn:
Cache-Control: no-storeContent-Security-Policy: default-src 'none'; frame-ancestors 'none'Strict-Transport-Security: max-age=31536000X-Content-Type-Options: nosniffX-Frame-Options: DENYReferrer-Policy: no-referrerDaarnaast wordt het verwachte JSON-mediatype gecontroleerd.
/core/transport/cors
Section titled “/core/transport/cors”Status: Voldoet
De beveiligde API-endpoints staan geen rechtstreekse cross-origin browsertoegang toe.
De conformance-tests controleren dat een externe origin geen Access-Control-Allow-Origin ontvangt en dat een preflight-request voor een beveiligd endpoint geen cross-origin toestemming krijgt.
Voor het publieke OpenAPI-document geldt bewust een ander beleid:
Access-Control-Allow-Origin: *Hierdoor kan het API-contract vanuit externe documentatie- en ontwikkeltools worden gelezen.
Normatieve modules
Section titled “Normatieve modules”/core/modules/geospatial
Section titled “/core/modules/geospatial”Status: Niet van toepassing
De huidige operations wisselen geen geometrie, horizontale coördinaten of ruimtelijke filters uit.
verticalDatum kwalificeert uitsluitend de scalar groundwater-level waarden en maakt de geospatial module op zichzelf niet van toepassing.
Deze beslissing is expliciet per conforming endpoint vastgelegd.
/core/modules/signing
Section titled “/core/modules/signing”Status: Niet van toepassing
End-to-end payload- of message signing is binnen de huidige trust boundary niet vereist.
Transportintegriteit wordt door de beveiligde verbinding afgedekt. Deze toepasselijkheidsbeslissing is expliciet vastgelegd.
/core/modules/encryption
Section titled “/core/modules/encryption”Status: Niet van toepassing
Application-level payload encryption is niet vereist.
Transportconfidentialiteit wordt door TLS geleverd. Deze toepasselijkheidsbeslissing is expliciet vastgelegd.
Openstaande aandachtspunten
Section titled “Openstaande aandachtspunten”Er zijn voor het huidige releasecontract geen bekende openstaande technische punten in de geautomatiseerde NLGov conformance-suite of Spectral-linting.
Voor de documentatie blijven twee inhoudelijke onderbouwingen relevant:
- leg de bron of rationale voor de gebruikte Engelse interfaceterminologie formeel vast;
- leg vast waarom het OpenAPI-document Engelstalig is terwijl de primaire gebruikersdocumentatie Nederlandstalig is.
Deze punten veranderen het huidige API-contract niet.
Conclusie
Section titled “Conclusie”De Avallo REST API voldoet voor het huidige v1-releasecontract aan de geautomatiseerd controleerbare technische eisen die in de Avallo conformance-suite voor NLGov REST API Design Rules 2.2.0 zijn vastgelegd.
Het gegenereerde OpenAPI-document voldoet daarnaast aan de gebruikte Spectral-ruleset, met één expliciet gemotiveerde uitzondering voor verticalDatum.
De beoordeling is transparant en herleidbaar, maar vormt geen onafhankelijke certificering. De twee resterende gedeeltelijke beoordelingen hebben betrekking op formele taalonderbouwing en niet op bekende functionele of beveiligingstechnische afwijkingen.