From 8a4c15e3facebd0600b9d3b125d12d115c4dbcb6 Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Mon, 19 May 2025 15:06:53 +0200 Subject: [PATCH 1/7] Beheer: status en datum CV --- js/config.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/js/config.js b/js/config.js index 3807a40..8a59086 100644 --- a/js/config.js +++ b/js/config.js @@ -149,12 +149,12 @@ globalThis.respecConfig = { ], github: "https://github.com/Logius-standaarden/API-Design-Rules", pubDomain: "api", - publishDate: "2025-02-17", - publishVersion: "2.0.2", - previousPublishDate: "2025-01-07", - previousPublishVersion: "2.0.1", + publishDate: "2025-05-19", + publishVersion: "2.1.0-rc.1", + previousPublishDate: "2025-02-17", + previousPublishVersion: "2.0.2", shortName: "adr", - specStatus: "WV", + specStatus: "CV", specType: "ST", pluralize: true, From 58b165491f6caf46826b21c6f0d7a9f9e7ad4861 Mon Sep 17 00:00:00 2001 From: Joost Farla Date: Fri, 13 Jun 2025 09:47:45 +0200 Subject: [PATCH 2/7] Beheer: aanscherping resource definities (#239) --- sections/designRules.md | 8 ++++---- sections/glossary.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index ab3d941..86eb3f7 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -2,7 +2,7 @@ ## Resources -The REST architectural style is centered around the concept of a [=resource=]. A resource is the key abstraction of information, where every piece of information is named by assigning a globally unique [=URI=] (Uniform Resource Identifier). Resources describe *things*, which can vary between physical objects (e.g. a building or a person) and more abstract concepts (e.g. a permit or an event). +The REST architectural style is centered around the concept of a [=resource=]. A resource is an abstraction of a conceptual entity, identified by a globally unique [=URI=]. It may correspond to anything from a physical object (e.g. a building or a person) to an abstract concept (e.g. a permit, an event or today's weather). Although a resource is not tied to any specific exchange format, its current state can be transferred to clients through one or more representations, such as JSON or XML.
@@ -10,7 +10,7 @@ The REST architectural style is centered around the concept of a [=resource=]. A
Statement
- Resources are referred to using nouns (instead of verbs) that are relevant from the perspective of the user of the API. + Resources are referred to using nouns (instead of verbs) that represent entities meaningful to the API consumer.
A few correct examples of nouns as part of a URI:
    @@ -31,7 +31,7 @@ The REST architectural style is centered around the concept of a [=resource=]. A
-A resource describing a single thing is called a [=singular resource=]. Resources can also be grouped into collections, which are resources in their own right and can typically be paged, sorted and filtered. Most often all collection members have the same type, but this is not necessarily the case. A resource describing multiple things is called a [=collection resource=]. Collection resources typically contain references to the underlying singular resources. +A resource that corresponds to a single conceptual entity is referred to as a [=singular resource=]. Resources can also be logically grouped into collections, which are themselves resources and typically support operations like paging, sorting, and filtering. While collection members are often of the same type, this is not strictly required. A collection resource contains references (URIs) to the individual singular resources it includes.
@@ -39,7 +39,7 @@ A resource describing a single thing is called a [=singular resource=]. Resource
Statement
- A collection resource represents multiple things. + Collection resources are referred to using plural nouns.
Rationale
diff --git a/sections/glossary.md b/sections/glossary.md index 715c75d..684d8b4 100644 --- a/sections/glossary.md +++ b/sections/glossary.md @@ -5,25 +5,25 @@ Resource
- A resource is the key abstraction of information, where every piece of information is identified by a globally unique [=URI=]. + A resource is an abstraction of a conceptual entity, identified by a globally unique [=URI=], whose current state can be transferred to clients through one or more representations.
Singular resource
- A singular resource is a resource describing a single thing (e.g. a building, person or event). + A singular resource is a resource that corresponds to a single conceptual entity (e.g. a building, person or event).
Collection resource
- A collection resource is a resource describing multiple things (e.g. a list of buildings). + A collection resource is a resource that corresponds to a logical grouping of related resources and contains references (URIs) to the individual singular resources it includes. (e.g. a list of buildings).
URI
- A URI [[rfc3986]] (Uniform Resource Identifier) is a globally unique identifier for a resource. + A URI [[rfc3986]] (Uniform Resource Identifier) is a string that identifies a resource. URIs are intended to be unique across the web, allowing resources to be unambiguously referenced.
OGC From 23b359635769adf4b7024c898c37da9c66d48f74 Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Wed, 2 Jul 2025 11:47:00 +0200 Subject: [PATCH 3/7] RC2 --- js/config.js | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/js/config.js b/js/config.js index 8a59086..57f4909 100644 --- a/js/config.js +++ b/js/config.js @@ -149,14 +149,15 @@ globalThis.respecConfig = { ], github: "https://github.com/Logius-standaarden/API-Design-Rules", pubDomain: "api", - publishDate: "2025-05-19", - publishVersion: "2.1.0-rc.1", + publishDate: "2025-07-01", + publishVersion: "2.1.0-rc.2", previousPublishDate: "2025-02-17", previousPublishVersion: "2.0.2", shortName: "adr", - specStatus: "CV", + specStatus: "VV", specType: "ST", pluralize: true, + thisVersion: [], preProcess: [initializeHighlightJSYaml, fetchSpectralConfiguration], postProcess: [highlightSpectralCode, processRuleBlocks], From 6fc3e4796f9f6955db822552df09945f864c3489 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 27 Aug 2025 15:27:52 +0200 Subject: [PATCH 4/7] Voeg definitieve versie toe Deze versie is vastgesteld door de PT GU op 21 augustus 2025. --- js/config.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/js/config.js b/js/config.js index 57f4909..a5ec504 100644 --- a/js/config.js +++ b/js/config.js @@ -149,12 +149,12 @@ globalThis.respecConfig = { ], github: "https://github.com/Logius-standaarden/API-Design-Rules", pubDomain: "api", - publishDate: "2025-07-01", - publishVersion: "2.1.0-rc.2", + publishDate: "2025-08-27", + publishVersion: "2.1.0", previousPublishDate: "2025-02-17", previousPublishVersion: "2.0.2", shortName: "adr", - specStatus: "VV", + specStatus: "DEF", specType: "ST", pluralize: true, thisVersion: [], From d61850c27dad5ae238bfd19ded03cb1d34168285 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 27 Aug 2025 15:31:30 +0200 Subject: [PATCH 5/7] Voeg 2.1.0 toe aan versietabel --- sections/sotd.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sections/sotd.md b/sections/sotd.md index c76648b..425fec0 100644 --- a/sections/sotd.md +++ b/sections/sotd.md @@ -2,3 +2,4 @@ |------------|----------------------------------------------------------------------|---------------------------------------------------------------------| | 2020-07-09 | [1.0]( https://gitdocumentatie.logius.nl/publicatie/api/adr/1.0) | Initial version based on input from Kennisplatform API's | | 2024-03-07 | [2.0.0](https://gitdocumentatie.logius.nl/publicatie/api/adr/2.0.0) | Add Geospatial and Transport Security modules | +| 2025-08-27 | [2.1.0](https://gitdocumentatie.logius.nl/publicatie/api/adr/2.1.0) | Add `info.contact` rule and linter configuration | From f9b2af6b9183dfed213800665c2a7dc36151868e Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Thu, 28 Aug 2025 13:13:52 +0200 Subject: [PATCH 6/7] typos --- sections/designRules.md | 4 ++-- sections/summary.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 86eb3f7..133a63c 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -550,7 +550,7 @@ servers:
How to test
- Parse the `url` field in the `servers` mentioned in the OpenAPI Description to confirm the a version number is present with prefix v and only contains the *major* version number. + Parse the `url` field in the `servers` mentioned in the OpenAPI Description to confirm that a version number is present with prefix v and only contains the *major* version number.
@@ -775,7 +775,7 @@ As for outbound filtering, the main concern is leaking of information.
How to test
-

The precense of the mandatory security headers can be tested in an automated way. A test client makes a call to the API root. The response is tested for the precense of mandatory headers. +

The presense of the mandatory security headers can be tested in an automated way. A test client makes a call to the API root. The response is tested for the presense of mandatory headers.

diff --git a/sections/summary.md b/sections/summary.md index 993927f..0ebcb5c 100644 --- a/sections/summary.md +++ b/sections/summary.md @@ -2,7 +2,7 @@ ### Normative Design Rules -Design rules can be technical rules, which should be tested automatically and functional rules which should be considerd when designing and building the api. +Design rules can be technical rules, which should be tested automatically and functional rules which should be considered when designing and building the api. #### List of functional rules From 54ef04ddcfccd0ac8ba12999a3c439cf36299238 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 2 Sep 2025 14:15:28 +0200 Subject: [PATCH 7/7] Fix line endings van RELEASING.md --- RELEASING.md | 144 +++++++++++++++++++++++++-------------------------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 12793e7..0d81fa5 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,72 +1,72 @@ -# Release procedure - -Om een nieuwe versie van deze standaard te publiceren, moeten er nieuwe commits op `main` worden gepusht. -Dit kan zowel met een losstaande PR (in het geval van kleine patch fixes) of het synchroniseren van `develop` als er een minor/major release klaar wordt gezet. - -# Versioning van deze standaard - -Deze standaard volgt het [API-standaarden beheermodel](https://gitdocumentatie.logius.nl/publicatie/api/beheermodel/). -Dit betekent dat deze standaard Semantic Versioning gebruikt in de vorm van MAJOR.MINOR.PATCH. - -Hierbij is er wel ambiguïteit in wat Minor versus Major changes zijn, aangezien nieuwe design rules een kleine of grote impact kunnen hebben op bestaande API's die conform de API Design Rules zijn gebouwd. -Om deze ambiguïteit te verduidelijken beschrijven we in deze sectie wat wel en niet valt onder Major, Minor en Patch changes bij het toevoegen van nieuwe design rules. - -Het wijzigen van bestaande design rules blijft een Major release. - -## Semantic versioning hangt af van of een API client moet worden aangepast - -Aangezien deze standaard allerlei design rules specificeert, komt het regelmatig voor dat nieuwe regels worden toegepast op basis van kennis opgedaan van bestaande implementaties. -Hierbij kan het voorkomen dat bestaande API's niet meer voldoen aan een nieuwe set van regels in een nieuwe versie. - -Op basis van de analyse van leden van het TO, Beheer en publieke consultatie wordt de impact van de nieuwe regel beoordeeld. -Als een nieuwe regel voor bestaande clients van een API veranderingen vereist, dan is de nieuwe versie Major. -Echter, als een nieuwe regel enkel veranderingen vereist aan een API en voor de rest niet resulteren in veranderingen van een API client, dan is de nieuwe versie Minor. - -### Voorbeeld: gebruik standaard HTTP-methodes is Minor - -API's worden vrijwel altijd met HTTP-methodes geïmplementeerd. -Het expliciet maken van deze requirement voorkomt ambiguïteit en API clients maken hier praktisch altijd gebruik van. -Een nieuwe versie van de standaard mag een Minor version zijn, omdat de intentie (en verwachting) is dat bestaande API clients compatibel zijn. - -### Voorbeeld: vereis versienummer in de URI is Major - -Het is een semantische kwestie of het versienummer van een API in de URI moet. -Dit betekent dat er in principe geen industrie-wijd consensus is over het wel, dan wel niet, toevoegen van een versienummer in de URI. -Bestaande API's kunnen hier een andere keuze in hebben gemaakt (lees wel: dit is een potentiële situatie; De design rules hebben van de start deze rule bevat). -Hierdoor is het goed mogelijk dat API clients de URL moeten veranderen. -Daarom zou het toevoegen van deze design rule onderdeel zijn van een Major release. - -## Interpretatie van versioning scheme wat betreft compliance - -Aangezien de regels in de toekomst kunnen worden uitgebreid is compliance gelinkt aan versies van de standaard. -Compliance aan de ADR heeft daarom de volgende eigenschappen: - -* Alle design rules in een nieuwe patch versie zullen dezelfde resultaten opleveren als eerdere patch versies binnen de minor release. - * Dit betekent dat de compliance checks draaien op de nieuwe patch versie dezelfde score oplevert. -* Bestaande design rules in een nieuwe minor versie zullen dezelfde resultaten opleveren als eerdere minor versies binnen de major release. -Nieuwe design rules in een minor versie kunnen in een kleine minderheid resulteren in nieuwe issues. - * Dit betekent dat in de meeste gevallen dat compliance checks draaien op de nieuwe versie, deze meestal dezelfde score oplevert. - Echter, er kunnen situaties zijn waar bestaande API's op enkele nieuwe regels niet direct compliant zijn. -* Design rules in een nieuwe major versie kunnen andere resultaten opleveren. -Hierbij wordt de impact afgewogen ten opzichte van de waarde van de nieuwe design rule. -Dit kunnen zowel nieuwe design rules die een verwachte grote impact hebben, veranderingen vereisen aan API clients of wijzigingen aan bestaande design rules. - -## Waarom wordt hier afgeweken van strict Semantic Versioning op basis van enkel de API's zelf? - -Het doel van Semantic Versioning is om inzicht te krijgen in de potentiële impact van een nieuwe versie voor de eindgebruiker. -Het versienummer is een communicatiemiddel tussen de maintainer en gebruiker. -Een Major version geeft een signaal af aan de gebruiker dat er een grote impact wordt verwacht. - -Deze standaard bevat design rules die limiterend zijn in welke keuzes beheerders van API's kunnen nemen. -Dit betekent dat keuzes van beheerders in het verleden mogelijk niet meer toe gestaan worden op basis van nieuwe inzichten. -Als Semantic Versioning strict wordt gevolgd, dan resulteert dit in (zeer) frequente Major releases, aangezien nieuwe regels potentieel bestaande API's non-compliant kunnen maken. -Het gevolg is dat elke nieuwe design rule van deze standaard een Major release introduceert. -Dit is in strijd met de intentie van Semantic Versioning, omdat hiermee de verwachtingen voor gebruikers onduidelijk wordt. -Niet alle nieuwe design rules hebben dezelfde impact, sommige mogelijk helemaal geen (bijvoorbeeld als er gesproken word over "industry standard"). - -Om gebruikers van API's zo goed mogelijk te informeren over de impact van wijzigingen wordt er dus gekeken naar de impact op de API clients. -Deze client impact wordt bepaald op basis van input van beheerders van bestaande API's via de, door de governance bepaalde, relevante gremia. -Hierbij is het speerpunt dat impact voor beheerders duidelijk moet zijn zodat inschattingen voor planning en prioritisering haalbaar zijn. -Deze impact inschatting is onhaalbaar als elke release een nieuwe Major version zou opleveren. - -Al met al zorgt dit ervoor dat de intentie van een release begrijpelijk is voor API-beheerders en afnemers. +# Release procedure + +Om een nieuwe versie van deze standaard te publiceren, moeten er nieuwe commits op `main` worden gepusht. +Dit kan zowel met een losstaande PR (in het geval van kleine patch fixes) of het synchroniseren van `develop` als er een minor/major release klaar wordt gezet. + +# Versioning van deze standaard + +Deze standaard volgt het [API-standaarden beheermodel](https://gitdocumentatie.logius.nl/publicatie/api/beheermodel/). +Dit betekent dat deze standaard Semantic Versioning gebruikt in de vorm van MAJOR.MINOR.PATCH. + +Hierbij is er wel ambiguïteit in wat Minor versus Major changes zijn, aangezien nieuwe design rules een kleine of grote impact kunnen hebben op bestaande API's die conform de API Design Rules zijn gebouwd. +Om deze ambiguïteit te verduidelijken beschrijven we in deze sectie wat wel en niet valt onder Major, Minor en Patch changes bij het toevoegen van nieuwe design rules. + +Het wijzigen van bestaande design rules blijft een Major release. + +## Semantic versioning hangt af van of een API client moet worden aangepast + +Aangezien deze standaard allerlei design rules specificeert, komt het regelmatig voor dat nieuwe regels worden toegepast op basis van kennis opgedaan van bestaande implementaties. +Hierbij kan het voorkomen dat bestaande API's niet meer voldoen aan een nieuwe set van regels in een nieuwe versie. + +Op basis van de analyse van leden van het TO, Beheer en publieke consultatie wordt de impact van de nieuwe regel beoordeeld. +Als een nieuwe regel voor bestaande clients van een API veranderingen vereist, dan is de nieuwe versie Major. +Echter, als een nieuwe regel enkel veranderingen vereist aan een API en voor de rest niet resulteren in veranderingen van een API client, dan is de nieuwe versie Minor. + +### Voorbeeld: gebruik standaard HTTP-methodes is Minor + +API's worden vrijwel altijd met HTTP-methodes geïmplementeerd. +Het expliciet maken van deze requirement voorkomt ambiguïteit en API clients maken hier praktisch altijd gebruik van. +Een nieuwe versie van de standaard mag een Minor version zijn, omdat de intentie (en verwachting) is dat bestaande API clients compatibel zijn. + +### Voorbeeld: vereis versienummer in de URI is Major + +Het is een semantische kwestie of het versienummer van een API in de URI moet. +Dit betekent dat er in principe geen industrie-wijd consensus is over het wel, dan wel niet, toevoegen van een versienummer in de URI. +Bestaande API's kunnen hier een andere keuze in hebben gemaakt (lees wel: dit is een potentiële situatie; De design rules hebben van de start deze rule bevat). +Hierdoor is het goed mogelijk dat API clients de URL moeten veranderen. +Daarom zou het toevoegen van deze design rule onderdeel zijn van een Major release. + +## Interpretatie van versioning scheme wat betreft compliance + +Aangezien de regels in de toekomst kunnen worden uitgebreid is compliance gelinkt aan versies van de standaard. +Compliance aan de ADR heeft daarom de volgende eigenschappen: + +* Alle design rules in een nieuwe patch versie zullen dezelfde resultaten opleveren als eerdere patch versies binnen de minor release. + * Dit betekent dat de compliance checks draaien op de nieuwe patch versie dezelfde score oplevert. +* Bestaande design rules in een nieuwe minor versie zullen dezelfde resultaten opleveren als eerdere minor versies binnen de major release. +Nieuwe design rules in een minor versie kunnen in een kleine minderheid resulteren in nieuwe issues. + * Dit betekent dat in de meeste gevallen dat compliance checks draaien op de nieuwe versie, deze meestal dezelfde score oplevert. + Echter, er kunnen situaties zijn waar bestaande API's op enkele nieuwe regels niet direct compliant zijn. +* Design rules in een nieuwe major versie kunnen andere resultaten opleveren. +Hierbij wordt de impact afgewogen ten opzichte van de waarde van de nieuwe design rule. +Dit kunnen zowel nieuwe design rules die een verwachte grote impact hebben, veranderingen vereisen aan API clients of wijzigingen aan bestaande design rules. + +## Waarom wordt hier afgeweken van strict Semantic Versioning op basis van enkel de API's zelf? + +Het doel van Semantic Versioning is om inzicht te krijgen in de potentiële impact van een nieuwe versie voor de eindgebruiker. +Het versienummer is een communicatiemiddel tussen de maintainer en gebruiker. +Een Major version geeft een signaal af aan de gebruiker dat er een grote impact wordt verwacht. + +Deze standaard bevat design rules die limiterend zijn in welke keuzes beheerders van API's kunnen nemen. +Dit betekent dat keuzes van beheerders in het verleden mogelijk niet meer toe gestaan worden op basis van nieuwe inzichten. +Als Semantic Versioning strict wordt gevolgd, dan resulteert dit in (zeer) frequente Major releases, aangezien nieuwe regels potentieel bestaande API's non-compliant kunnen maken. +Het gevolg is dat elke nieuwe design rule van deze standaard een Major release introduceert. +Dit is in strijd met de intentie van Semantic Versioning, omdat hiermee de verwachtingen voor gebruikers onduidelijk wordt. +Niet alle nieuwe design rules hebben dezelfde impact, sommige mogelijk helemaal geen (bijvoorbeeld als er gesproken word over "industry standard"). + +Om gebruikers van API's zo goed mogelijk te informeren over de impact van wijzigingen wordt er dus gekeken naar de impact op de API clients. +Deze client impact wordt bepaald op basis van input van beheerders van bestaande API's via de, door de governance bepaalde, relevante gremia. +Hierbij is het speerpunt dat impact voor beheerders duidelijk moet zijn zodat inschattingen voor planning en prioritisering haalbaar zijn. +Deze impact inschatting is onhaalbaar als elke release een nieuwe Major version zou opleveren. + +Al met al zorgt dit ervoor dat de intentie van een release begrijpelijk is voor API-beheerders en afnemers.