From 382b2ec3a71cfc2190aa3e109f2e79768491fd96 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Tue, 18 Jul 2023 12:45:17 +0200 Subject: [PATCH 01/13] Added a conditional TLS module rule --- DesignRules.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 5034b27..7b2b6a6 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -1,4 +1,4 @@ -# The Design Rules +# The core set of Design Rules ## Resources @@ -446,6 +446,39 @@ Resources are often interconnected by relationships. Relationships can be modell

+## Conditional Modules + +As described in the Extensions paragraph the NL API Strategy is composed of a set of modules that are extentions on the Core set of Design Rules. The modules are optional or conditional. Optional rules can be found in the infographic. All conditional modules are referenced in this document and the 'conditional usage' is formalized as a unique designrule. + + +
+

/core/conditional/transport-security: Apply transport security conform the module

+
+
Statement
+
+ When handling government data the transport security module MUST be applied. +
+
Rationale
+
+ The transport security module as described and published on Github formalizes three simple rules to apply to API's: +
    +
  1. Secure connections using TLS
    2. +
  2. No sensitive information in URIs
    3. +
  3. Use CORS to control access
    4. +
+ Furthermore the module describes best practices for security headers, browser-based applications, and other HTTP configurations. These best practices Must be considerd and the considerations SHOULD be published in the API documentation. Hence the transport security is the baseline for REST API resources and the data concerned is a vital asset of the government the rules and best practices are condiderd the minimal security principles, concepts and technologies to apply. +
+
Implications
+
+ Adherance to this rule needs to be manually verified. Some rules of the module COULD be tested automatically and will be shown on developer.overheid.nl. The source code of these technical test can be found here. The specific tests are published in the [[ADR-Validator]] repository. +
+
Rule types
+
+ This is a functional design rule and hence can't be tested automatically. +
+
+
+ ## Documentation An API is as good as the accompanying documentation. The documentation has to be easily findable, searchable and publicly accessible. Most developers will first read the documentation before they start implementing. Hiding the technical documentation in PDF documents and/or behind a login creates a barrier for both developers and search engines. From 8a2feed72ed0e5892a6c43586df99832ee5be3e0 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 15:32:58 +0200 Subject: [PATCH 02/13] typos fixed Co-authored-by: Alexander Green --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 7b2b6a6..702c291 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -448,7 +448,7 @@ Resources are often interconnected by relationships. Relationships can be modell ## Conditional Modules -As described in the Extensions paragraph the NL API Strategy is composed of a set of modules that are extentions on the Core set of Design Rules. The modules are optional or conditional. Optional rules can be found in the infographic. All conditional modules are referenced in this document and the 'conditional usage' is formalized as a unique designrule. +As described in the Extensions paragraph the NL API Strategy is composed of a set of modules that are extensions on the Core set of Design Rules. The modules are optional or conditional. Optional modules can be found in the infographic. All conditional modules are referenced in this document and the 'conditional usage' is formalized as a unique design rule.
From 4ab6cb888023db70447a44ee24a4022ac9921844 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 15:34:10 +0200 Subject: [PATCH 03/13] textual formulation enhancements Co-authored-by: Alexander Green --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 702c291..166ee54 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -460,7 +460,7 @@ As described in the Extensions paragraph the NL API St
Rationale
- The transport security module as described and published on Github formalizes three simple rules to apply to API's: + The transport security module as described and published on Github formalizes three rules to apply to APIs:
  1. Secure connections using TLS
  2. No sensitive information in URIs
    3. From c1c7715b68f68c100abb7b63f10a9edc116adf21 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 15:34:48 +0200 Subject: [PATCH 04/13] typos fixed Co-authored-by: Alexander Green --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 166ee54..4098190 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -466,7 +466,7 @@ As described in the Extensions paragraph the NL API St
  3. No sensitive information in URIs
  4. Use CORS to control access
- Furthermore the module describes best practices for security headers, browser-based applications, and other HTTP configurations. These best practices Must be considerd and the considerations SHOULD be published in the API documentation. Hence the transport security is the baseline for REST API resources and the data concerned is a vital asset of the government the rules and best practices are condiderd the minimal security principles, concepts and technologies to apply. + Furthermore the module describes best practices for security headers, browser-based applications, and other HTTP configurations. These best practices MUST be considered and the considerations SHOULD be published in the API documentation. Hence the transport security is the baseline for REST API resources and the data concerned is a vital asset of the government the rules and best practices are condidered the minimal security principles, concepts and technologies to apply.
Implications
From da11e944da3774006e19bebabed7558ad4887652 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 15:46:00 +0200 Subject: [PATCH 05/13] typos fixed Co-authored-by: Alexander Green --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 4098190..2288f1b 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -470,7 +470,7 @@ As described in the Extensions paragraph the NL API St
Implications
- Adherance to this rule needs to be manually verified. Some rules of the module COULD be tested automatically and will be shown on developer.overheid.nl. The source code of these technical test can be found here. The specific tests are published in the [[ADR-Validator]] repository. + Adherence to this rule needs to be manually verified. Some rules of the module COULD be tested automatically and will be shown on developer.overheid.nl. The source code of these technical test can be found here. The specific tests are published in the [[ADR-Validator]] repository.
Rule types
From 9e9b762be767b29919e41426c5ba4b02e3b18a18 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 15:48:09 +0200 Subject: [PATCH 06/13] typos fixed --- DesignRules.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 2288f1b..eafd664 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -30,7 +30,7 @@ The REST architectural style is centered around the concept of a [resource](#dfn
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -69,7 +69,7 @@ A resource describing a single thing is called a [singular resource](#dfn-singul
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -93,7 +93,7 @@ A resource describing a single thing is called a [singular resource](#dfn-singul
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -363,7 +363,7 @@ Stateless communication offers many advantages, including:
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -404,7 +404,7 @@ Resources are often interconnected by relationships. Relationships can be modell
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -434,7 +434,7 @@ Resources are often interconnected by relationships. Relationships can be modell
Implications
In this design rule, approach 2 and 3 are preferred. - Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -521,7 +521,7 @@ An API is as good as the accompanying documentation. The documentation has to be
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -579,7 +579,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -602,7 +602,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
@@ -652,7 +652,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
Implications
- Adherance to this rule needs to be manually verified. + Adherence to this rule needs to be manually verified.
Rule types
From aaba52aa8a2a5eb8f03048896407b9371fd9474b Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 16:25:56 +0200 Subject: [PATCH 07/13] update link to transport security --- DesignRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index eafd664..a9f9cb4 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -452,7 +452,7 @@ As described in the Extensions paragraph the NL API St
-

/core/conditional/transport-security: Apply transport security conform the module

+

/core/conditional/transport-security: Apply the transport security module

Statement
@@ -460,7 +460,7 @@ As described in the Extensions paragraph the NL API St
Rationale
- The transport security module as described and published on Github formalizes three rules to apply to APIs: + The transport security module as described and published on Github formalizes three rules to apply to APIs:
  1. Secure connections using TLS
  2. No sensitive information in URIs
    3. From 32dd0768b6449198c4640e90549778f8189156ac Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 16:28:46 +0200 Subject: [PATCH 08/13] review comments --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index a9f9cb4..9412eb0 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -470,7 +470,7 @@ As described in the Extensions paragraph the NL API St
Implications
- Adherence to this rule needs to be manually verified. Some rules of the module COULD be tested automatically and will be shown on developer.overheid.nl. The source code of these technical test can be found here. The specific tests are published in the [[ADR-Validator]] repository. + Adherence to this rule needs to be manually verified. Some rules of the module COULD be tested automatically and will be shown on developer.overheid.nl. The source code of the technical test can be found here. The specific tests are published in the [[ADR-Validator]] repository.
Rule types
From dedb78793ef86c9003c9a5211ccd4197d0c2bf06 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 20 Sep 2023 16:32:04 +0200 Subject: [PATCH 09/13] update link to infographic --- Introduction.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Introduction.md b/Introduction.md index 57e1781..a9f71ee 100644 --- a/Introduction.md +++ b/Introduction.md @@ -29,8 +29,10 @@ The Nederlandse API Strategie consists of [three layers of distinct documents](h Before reading this document it is advised to gain knowledge of the three documents, in particular [the architecture section of part I](https://docs.geostandaarden.nl/api/API-Strategie/#architectuur). An actual overview of all current documents is available in this Dutch infographic: -![NL API Strategie Infographic](https://raw.githubusercontent.com/Geonovum/KP-APIs/a0ee2f718777eb333a4e625edb1e8ce1387b51d3/media/API_infographic.svg) - +
+ +
NL API Strategie Infographic
+
## Extensions