From e17eb874d32174be38d4f221b9b815dae6d12010 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Fri, 17 Jan 2025 11:57:21 +0100 Subject: [PATCH 1/7] Voeg naming-conventions toe aan standaard De naming-conventions zijn ontwikkeld als onderdeel van het kennisplatform APIs als aparte module. Deze commit integreert de conventions in de standaard als rules om overhead te voorkomen en alle rules verplicht te maken (in tegenstelling tot een module die niet altijd nodig is). --- DesignRules.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/DesignRules.md b/DesignRules.md index b1a0f03..fa84aa9 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -66,6 +66,44 @@ A resource describing a single thing is called a [=singular resource=]. Resource +
+

Do not use abbreviations (except standarized) in a resource name

+
+
Statement
+
+ A resource MUST NOT use abbreviations, except standardized abbreviations as defined by the API or organisation itself. +
+
Rationale
+
+

Abbreviations can have multiple definitions depending on the context. Improve understanding by not using these abbreviations. +

+

URI including abbreviations (incorrect):

+ 
https://api.example.org/v1/gebouwen/19/coords
+

URI avoiding abbreviations (correct):

+ 
https://api.example.org/v1/gebouwen/19/coordinates
+
+

The exception to this rule are abbreviations solely related to the API itself or the organisation. In the example below, the Kadaster API includes the abbrevation BAG which is a standardized definition for "Basisregistratie Adressen en Gebouwen" used in all Kadaster contexts. +

+

URI including standardized abbreviations (correct):

+ 
https://api.bag.kadaster.nl/contractloos/v2/bag
+
+

This rule does not apply to variables used in API documentation. Authors are advised to avoid abbreviations in documentation (examples) to improve understanding to readers unfamiliar with the context. The abbreviation Id MAY be used instead of Identificatie or IdentificatieNummer +

+

Documentation including a URI with abbreviations in variable (discouraged):

+ 
https://api.example.org/v1/gebouwen/{gbId}
+

Documentation including a URI without abbreviations in variable (advised):

+ 
https://api.example.org/v1/gebouwen/{gebouwId}
+

Documentation including a URI with standardized abbreviations in variable (advised):

+ 
https://api.bag.kadaster.nl/contractloos/v2/bag/{bagId}
+
+
+
Implications
+
+ Adherence to this rule needs to be manually verified. +
+
+
+

Define interfaces in Dutch unless there is an official English glossary available

@@ -113,6 +151,85 @@ A resource describing a single thing is called a [=singular resource=]. Resource
+
+

Use kebab-case in path segments

+
+
Statement
+
+
+

Path segments of a [=URI=] MUST only contain lowercase letters, digits or hyphens. This is also known as kebab-case. Hyphens MUST only be used to deliniate distinct words. This also implies that diacritics MUST be normalized and special characters MUST be omitted. +

Another implication of this rule is that file extensions MUST NOT be used. Resources SHOULD use the Accept header for content negotation. +

+
+
Rationale
+
+

Some web servers and frameworks do not handle case sensitivity or special characters of URI's well. The use of kebab-case path segments ensures compatibility with a broad range of systems. It is a more common implementation choice for path segments than camelCase or snake_case. +

+

URI path segment using kebab-case (correct):

+ 
https://api.example.org/v1/organisatie-codes
+

URI path segment not using hyphens to delineate words (incorrect):

+ 
https://api.example.org/v1/organisatie_codes
+

URI path segment ending with a hyphen (incorrect):

+ 
https://api.example.org/v1/organisatie-
+

URI path segment starting with a hyphen (incorrect):

+ 
https://api.example.org/v1/-organisatie
+

URI path segment using normalized diacritics (correct):

+ 
https://api.example.org/v1/scenes
+

URI path segment using diacritics (incorrect):

+ 
https://api.example.org/v1/scènes
+

URI path segment omitting special characters (correct):

+ 
https://api.example.org/v1/schemas
+

URI path segment using special characters (incorrect):

+ 
https://api.example.org/v1/schema's
+
+
+
Implications
+
+ This rule can be tested automatically and an example of the test is included in the automatic tests on developer.overheid.nl. The specific tests are published in the [[ADR-Validator]] repository. +
+
How to test
+
+ Loop all resource paths in the OpenAPI Description and check that all resource path segments use lowercase letters, digits or hyphens (-). You can use the following regex to check each path segment: +
+ 
^[a-z0-9]+(\-[a-z0-9]+)*$
+
+
+
+
+ +
+

Use camelCase in query keys

+
+
Statement
+
+
+

Query keys [=URI=] MUST only contain letters, digits in camelCase. This also implies that diacritics MUST be normalized and special characters MUST be omitted. +

+
+
Rationale
+
+

Query keys are often converted to JSON object keys, where camelCase is the naming convention to avoid compatibility issues with JavaScript when deserializing objects. +

+

URI query key using camelCase (correct):

+ 
https://api.example.org/v1/gebouwen?typeGebouw=woning
+

URI query key not using camelCase (incorrect):

+ 
https://api.example.org/v1/gebouwen?type-gebouw=woning
+
+
+
Implications
+
+ This rule can be tested automatically and an example of the test is included in the automatic tests on developer.overheid.nl. The specific tests are published in the [[ADR-Validator]] repository. +
+
How to test
+
+ Loop all resource paths in the OpenAPI Description and check that all query keys use letters, digits in camelCase. You can use the following regex for each query key: +
+ 
^[a-z0-9]+([A-Z][a-z0-9]+)*$
+
+
+
+
+

Hide irrelevant implementation details

From 90dec75fe8064e39c7827934681252991a251370 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Fri, 17 Jan 2025 12:15:06 +0100 Subject: [PATCH 2/7] Fix issues gevonden door review --- DesignRules.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index fa84aa9..dfc1ef6 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -98,9 +98,7 @@ A resource describing a single thing is called a [=singular resource=]. Resource
Implications
-
- Adherence to this rule needs to be manually verified. -
+
@@ -151,7 +149,7 @@ A resource describing a single thing is called a [=singular resource=]. Resource -
+

Use kebab-case in path segments

Statement
From c3627946e5d778746fd424d7776f32fa0c296941 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Mon, 20 Jan 2025 11:50:45 +0100 Subject: [PATCH 3/7] Standaard afkortingen moeten in een glossary staan Hiermee zorgen we ervoor dat een API wel een standaard afkorting mag gebruiken, maar dat ook voor een leek duidelijk is op basis van de documentatie waar die afkorting voor staat. --- DesignRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index dfc1ef6..f69a784 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -82,12 +82,12 @@ A resource describing a single thing is called a [=singular resource=]. Resource

URI avoiding abbreviations (correct):

https://api.example.org/v1/gebouwen/19/coordinates
-

The exception to this rule are abbreviations solely related to the API itself or the organisation. In the example below, the Kadaster API includes the abbrevation BAG which is a standardized definition for "Basisregistratie Adressen en Gebouwen" used in all Kadaster contexts. +

The exception to this rule are abbreviations solely related to the API itself or the organisation. When you exempt an abbreviation from this rule, there MUST be a glossary entry in the API documentation. The glossary entry SHOULD link to an external definition of the abbreviation. In the example below, the Kadaster API includes the abbrevation BAG which is a standardized definition for "Basisregistratie Adressen en Gebouwen" used in all Kadaster contexts.

URI including standardized abbreviations (correct):

https://api.bag.kadaster.nl/contractloos/v2/bag
-

This rule does not apply to variables used in API documentation. Authors are advised to avoid abbreviations in documentation (examples) to improve understanding to readers unfamiliar with the context. The abbreviation Id MAY be used instead of Identificatie or IdentificatieNummer +

This rule does not apply to variables used in API documentation. Authors MAY avoid abbreviations in documentation (examples) to improve understanding to readers unfamiliar with the context. The abbreviation Id MAY be used instead of Identificatie or IdentificatieNummer

Documentation including a URI with abbreviations in variable (discouraged):

https://api.example.org/v1/gebouwen/{gbId}
From e56e99edbfa12185eafccc146cba25130bca05a2 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 21 Jan 2025 10:27:58 +0100 Subject: [PATCH 4/7] Zet code highlighting uit voor URIs --- DesignRules.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index f69a784..145c7ae 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -78,23 +78,23 @@ A resource describing a single thing is called a [=singular resource=]. Resource

Abbreviations can have multiple definitions depending on the context. Improve understanding by not using these abbreviations.

URI including abbreviations (incorrect):

- 
https://api.example.org/v1/gebouwen/19/coords
+ 
https://api.example.org/v1/gebouwen/19/coords

URI avoiding abbreviations (correct):

- 
https://api.example.org/v1/gebouwen/19/coordinates
+ 
https://api.example.org/v1/gebouwen/19/coordinates

The exception to this rule are abbreviations solely related to the API itself or the organisation. When you exempt an abbreviation from this rule, there MUST be a glossary entry in the API documentation. The glossary entry SHOULD link to an external definition of the abbreviation. In the example below, the Kadaster API includes the abbrevation BAG which is a standardized definition for "Basisregistratie Adressen en Gebouwen" used in all Kadaster contexts.

URI including standardized abbreviations (correct):

- 
https://api.bag.kadaster.nl/contractloos/v2/bag
+ 
https://api.bag.kadaster.nl/contractloos/v2/bag

This rule does not apply to variables used in API documentation. Authors MAY avoid abbreviations in documentation (examples) to improve understanding to readers unfamiliar with the context. The abbreviation Id MAY be used instead of Identificatie or IdentificatieNummer

Documentation including a URI with abbreviations in variable (discouraged):

- 
https://api.example.org/v1/gebouwen/{gbId}
+ 
https://api.example.org/v1/gebouwen/{gbId}

Documentation including a URI without abbreviations in variable (advised):

- 
https://api.example.org/v1/gebouwen/{gebouwId}
+ 
https://api.example.org/v1/gebouwen/{gebouwId}

Documentation including a URI with standardized abbreviations in variable (advised):

- 
https://api.bag.kadaster.nl/contractloos/v2/bag/{bagId}
+ 
https://api.bag.kadaster.nl/contractloos/v2/bag/{bagId}
Implications
@@ -164,21 +164,21 @@ A resource describing a single thing is called a [=singular resource=]. Resource

Some web servers and frameworks do not handle case sensitivity or special characters of URI's well. The use of kebab-case path segments ensures compatibility with a broad range of systems. It is a more common implementation choice for path segments than camelCase or snake_case.

URI path segment using kebab-case (correct):

- 
https://api.example.org/v1/organisatie-codes
+ 
https://api.example.org/v1/organisatie-codes

URI path segment not using hyphens to delineate words (incorrect):

- 
https://api.example.org/v1/organisatie_codes
+ 
https://api.example.org/v1/organisatie_codes

URI path segment ending with a hyphen (incorrect):

- 
https://api.example.org/v1/organisatie-
+ 
https://api.example.org/v1/organisatie-

URI path segment starting with a hyphen (incorrect):

- 
https://api.example.org/v1/-organisatie
+ 
https://api.example.org/v1/-organisatie

URI path segment using normalized diacritics (correct):

- 
https://api.example.org/v1/scenes
+ 
https://api.example.org/v1/scenes

URI path segment using diacritics (incorrect):

- 
https://api.example.org/v1/scènes
+ 
https://api.example.org/v1/scènes

URI path segment omitting special characters (correct):

- 
https://api.example.org/v1/schemas
+ 
https://api.example.org/v1/schemas

URI path segment using special characters (incorrect):

- 
https://api.example.org/v1/schema's
+ 
https://api.example.org/v1/schema's
Implications
@@ -209,9 +209,9 @@ A resource describing a single thing is called a [=singular resource=]. Resource

Query keys are often converted to JSON object keys, where camelCase is the naming convention to avoid compatibility issues with JavaScript when deserializing objects.

URI query key using camelCase (correct):

- 
https://api.example.org/v1/gebouwen?typeGebouw=woning
+ 
https://api.example.org/v1/gebouwen?typeGebouw=woning

URI query key not using camelCase (incorrect):

- 
https://api.example.org/v1/gebouwen?type-gebouw=woning
+ 
https://api.example.org/v1/gebouwen?type-gebouw=woning
Implications
From 2d7a3240a0df0ac5eb2ac2614048192ae9de52c3 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 21 Jan 2025 10:31:31 +0100 Subject: [PATCH 5/7] Verduidelijking welke onderdelen van een URI de regels voor zijn --- DesignRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 145c7ae..22471aa 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -161,7 +161,7 @@ A resource describing a single thing is called a [=singular resource=]. Resource
Rationale
-

Some web servers and frameworks do not handle case sensitivity or special characters of URI's well. The use of kebab-case path segments ensures compatibility with a broad range of systems. It is a more common implementation choice for path segments than camelCase or snake_case. +

Some web servers and frameworks do not handle case sensitivity or special characters of URI's well. The use of kebab-case path segments ensures compatibility with a broad range of systems. It is a more common implementation choice for path segments than camelCase or snake_case. Information (such as names of objects) require special characters, they can be part of the request body instead of encoded in the URI.

URI path segment using kebab-case (correct):

https://api.example.org/v1/organisatie-codes
@@ -201,7 +201,7 @@ A resource describing a single thing is called a [=singular resource=]. Resource
Statement
-

Query keys [=URI=] MUST only contain letters, digits in camelCase. This also implies that diacritics MUST be normalized and special characters MUST be omitted. +

Query keys in a [=URI=] MUST only contain letters, digits in camelCase. This also implies that diacritics MUST be normalized and special characters MUST be omitted.

Rationale
From 7495d61d81fac60462113fbb236e595600947f79 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 21 Jan 2025 15:26:06 +0100 Subject: [PATCH 6/7] Update regex voor camelCase Zodat enkele letters aan het einde van een naam ook zijn toegestaan. --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 22471aa..c12b078 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -222,7 +222,7 @@ A resource describing a single thing is called a [=singular resource=]. Resource
Loop all resource paths in the OpenAPI Description and check that all query keys use letters, digits in camelCase. You can use the following regex for each query key:
- 
^[a-z0-9]+([A-Z][a-z0-9]+)*$
+ 
^[a-z0-9]+([A-Z][a-z0-9]+)*([A-Z])?$
From 76702a32e960ec417b3fa01024d31a327bcdde88 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 22 Jan 2025 12:19:15 +0100 Subject: [PATCH 7/7] Sta meerdere uppercase characters toe De regex is als voorbeeld bedoeld en kan niet alle edge cases af vangen waar semantisch wel of niet camelCase moet worden toegepast. Om verwarring te voorkomen is de regex permissive en wordt er vanuit gegaan dat bij een code review gekeken wordt of de intentie van camelCase correct wordt nageleefd. --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index c12b078..fc87d32 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -222,7 +222,7 @@ A resource describing a single thing is called a [=singular resource=]. Resource
Loop all resource paths in the OpenAPI Description and check that all query keys use letters, digits in camelCase. You can use the following regex for each query key:
- 
^[a-z0-9]+([A-Z][a-z0-9]+)*([A-Z])?$
+ 
^[a-z0-9]+[a-zA-Z0-9]*$