From 39d0428bd6d17e40b4807984cd2f74ef325a24bc Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 19 Apr 2023 12:52:38 +0200 Subject: [PATCH 01/13] eerste opzet voor verdieping how to test --- DesignRules.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 70de56d..8198902 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -216,7 +216,16 @@ Although the REST architectural style does not impose a specific protocol, REST
Implications
- This rule is included in the automatic tests 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. + This rule is included in the automatic tests on developer.overheid.nl. The source code of the technical test can be found at line 43 in the rules.go testscript. The specific testscripts are published in the [[ADR-Validator]] repository. +
+
How to test
+
+ - Step1-Test: the API Should meet the prerequisets to be tested. The include that an OAS file is present, parsable and all $refs are resolvable. + - Step1-Error: Error at line 49 - "Path '%s' has no methods" + - Step2-test: loop over all paths in the OAS file to check if methods are allowed. + - Step2-Error: tbd + - Step3-Test: Try non standard methods on the base url mentioned in the OAS file. + - Step3-Error: Error at line 95 - "Server responds to non-standard methods: %s"
Rule types
From d87d53fe13254f087e4f4eef782e0d1fb1d9705a Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Mon, 24 Apr 2023 14:35:44 +0200 Subject: [PATCH 02/13] Update DesignRules.md --- DesignRules.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index d188cd3..7bfad1e 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -220,12 +220,14 @@ Although the REST architectural style does not impose a specific protocol, REST
How to test
- - Step1-Test: the API Should meet the prerequisets to be tested. The include that an OAS file is present, parsable and all $refs are resolvable. - - Step1-Error: Error at line 49 - "Path '%s' has no methods" - - Step2-test: loop over all paths in the OAS file to check if methods are allowed. - - Step2-Error: tbd - - Step3-Test: Try non standard methods on the base url mentioned in the OAS file. - - Step3-Error: Error at line 95 - "Server responds to non-standard methods: %s" +
    +
  1. Step1-Test: the API Should meet the prerequisets to be tested. The include that an OAS file is present, parsable and all $refs are resolvable.
    2. +
  2. Step1-Error: Error at line 49 - "Path '%s' has no methods"
    3. +
  3. Step2-test: loop over all paths in the OAS file to check if methods are allowed.
    4. +
  4. Step2-Error: tbd
    5. +
  5. Step3-Test: Try non standard methods on the base url mentioned in the OAS file.
    6. +
  6. Step3-Error: Error at line 95 - "Server responds to non-standard methods: %s"
    7. +
Rule types
From 5de97854fb1a4dd9b55aa21822b393a8159277a4 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Tue, 25 Apr 2023 10:54:18 +0200 Subject: [PATCH 03/13] Update DesignRules.md --- DesignRules.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 7bfad1e..4e78eec 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -220,14 +220,10 @@ Although the REST architectural style does not impose a specific protocol, REST
How to test
-
    -
  1. Step1-Test: the API Should meet the prerequisets to be tested. The include that an OAS file is present, parsable and all $refs are resolvable.
    2. -
  2. Step1-Error: Error at line 49 - "Path '%s' has no methods"
    3. -
  3. Step2-test: loop over all paths in the OAS file to check if methods are allowed.
    4. -
  4. Step2-Error: tbd
    5. -
  5. Step3-Test: Try non standard methods on the base url mentioned in the OAS file.
    6. -
  6. Step3-Error: Error at line 95 - "Server responds to non-standard methods: %s"
    7. -
+
Rule types
@@ -477,6 +473,14 @@ An API is as good as the accompanying documentation. The documentation has to be
Implications
This rule is included in the automatic tests 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. +
+
How to test
+
+ +
  • Step3-Test: all references must be resolvable. Step3-Error: Failed to parse OpenAPI Specification https://gitlab.com/commonground/don/adr-validator/-/blob/v0.3.0/pkg/adr/rules.go#L147
    • Rule types
    @@ -609,6 +613,14 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    This rule is included in the automatic tests 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.
    +
    How to test
    +
    + +
  • Step2-Test: Each Server element of the OpenAPI Specification must include a version number. Step1-Error: Error at line 191 - "OpenAPI Specification server property contains invalid URL's"
    • + +
    Rule types
    This is a technical design rule and hence should be tested automatically. From 5713e3b9d26c31308e21351cac29a9e93f7bfdd9 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Tue, 25 Apr 2023 17:38:29 +0200 Subject: [PATCH 04/13] How to test update --- DesignRules.md | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 4e78eec..143396f 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -216,13 +216,13 @@ Although the REST architectural style does not impose a specific protocol, REST
    Implications
    - This rule is included in the automatic tests on developer.overheid.nl. The source code of the technical test can be found at line 43 in the rules.go testscript. The specific testscripts are published in the [[ADR-Validator]] repository. + This rule is included in the automatic tests on developer.overheid.nl. The source code of the technical test can be found at line 43 in the rules.go testscript. The specific testscripts are published in the [[ADR-Validator]] repository.
    How to test
    Rule types
    @@ -472,15 +472,15 @@ An API is as good as the accompanying documentation. The documentation has to be
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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.
    -
    How to test
    -
    - -
  • Step3-Test: all references must be resolvable. Step3-Error: Failed to parse OpenAPI Specification https://gitlab.com/commonground/don/adr-validator/-/blob/v0.3.0/pkg/adr/rules.go#L147
    • +
    How to test
    +
    +
    Rule types
    @@ -611,16 +611,15 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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. +
    +
    How to test
    +
    +
    -
    How to test
    -
    - -
  • Step2-Test: Each Server element of the OpenAPI Specification must include a version number. Step1-Error: Error at line 191 - "OpenAPI Specification server property contains invalid URL's"
    • - -
    Rule types
    This is a technical design rule and hence should be tested automatically. From e1fe77dd83d71baacd280d1ebfc5f93d56c40d03 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 26 Apr 2023 17:21:59 +0200 Subject: [PATCH 05/13] update how to tests descriptions --- DesignRules.md | 79 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 66 insertions(+), 13 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 143396f..92d4572 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -122,7 +122,20 @@ A resource describing a single thing is called a [singular resource](#dfn-singul
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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. +
    +
    How to test
    +
    +
    Rule types
    @@ -220,9 +233,11 @@ Although the REST architectural style does not impose a specific protocol, REST
    How to test
    -
    Rule types
    @@ -345,7 +360,7 @@ Although the REST architectural style does not impose a specific protocol, REST One of the key constraints of the REST architectural style is stateless communication between client and server. It means that every request from client to server must contain all of the information necessary to understand the request. The server cannot take advantage of any stored session context on the server as it didn’t memorize previous requests. Session state must therefore reside entirely on the client. To properly understand this constraint, it's important to make a distinction between two different kinds of state: -* *Session state*: information about the interactions of an end user with a particular client application within the same user session, such as the last page being viewed, the login state or form data in a multi-step registration process. Session state must reside entirely on the client (e.g. in the user's browser). +* *Session state*: information about the interactions of an end user with a particular client application within the same user session, such as the last page being viewed, the login state or form data in a multi-Step registration process. Session state must reside entirely on the client (e.g. in the user's browser). * *Resource state*: information that is permanently stored on the server beyond the scope of a single user session, such as the user's profile, a product purchase or information about a building. Resource state is persisted on the server and must be exchanged between client and server (in both directions) using representations as part of the request or response payload. This is actually where the term *REpresentational State Transfer (REST)* originates from.

    It's a misconception that there should be no state at all. The stateless communication constraint should be seen from the server's point of view and states that the server should not be aware of any session state.

    @@ -477,9 +492,12 @@ An API is as good as the accompanying documentation. The documentation has to be
    How to test
    Rule types
    @@ -534,7 +552,20 @@ An API is as good as the accompanying documentation. The documentation has to be
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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. +
    +
    How to test
    +
    +
    Rule types
    @@ -616,8 +647,10 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    How to test
    Rule types
    @@ -664,7 +697,18 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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. +
    +
    How to test
    +
    +
    Rule types
    @@ -692,7 +736,16 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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. +
    +
    How to test
    +
    +
    Rule types
    From e68418a571bd1eb407a9ad7295a1bc5e9d59352e Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Wed, 3 May 2023 18:24:07 +0200 Subject: [PATCH 06/13] test rules en steps bijgewerkt --- DesignRules.md | 140 ++++++++++++++++++++++--------------------------- 1 file changed, 64 insertions(+), 76 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 92d4572..4d1b2d9 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -124,23 +124,19 @@ A resource describing a single thing is called a [singular resource](#dfn-singul
    This rule is included in the automatic tests 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
    +
    + This is a technical design rule and hence should be tested automatically. +
    How to test
    -
    Rule types
    -
    - This is a technical design rule and hence should be tested automatically. -
    @@ -229,22 +225,8 @@ Although the REST architectural style does not impose a specific protocol, REST
    Implications
    - This rule is included in the automatic tests on developer.overheid.nl. The source code of the technical test can be found at line 43 in the rules.go testscript. The specific testscripts are published in the [[ADR-Validator]] repository. + This rule is included in the automatic tests on developer.overheid.nl. The source code of the technical test can be found here. The specific testscripts are published in the [[ADR-Validator]] repository.
    -
    How to test
    -
    - -
    -
    Rule types
    -
    - This is a technical design rule and hence should be tested automatically. -
    -
    The following table shows some examples of the use of standard HTTP methods: @@ -283,6 +265,18 @@ Although the REST architectural style does not impose a specific protocol, REST

    The HTTP specification [[rfc7231]] and the later introduced PATCH method specification [[rfc5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS and TRACE. For the purpose of this design rule, these operations are left out of scope.

    +
    How to test
    +
    + +
    +
    Rule types
    +
    + This is a technical design rule and hence should be tested automatically. +
    + @@ -489,21 +483,18 @@ An API is as good as the accompanying documentation. The documentation has to be
    This rule is included in the automatic tests 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
    +
    + This is a technical design rule and hence should be tested automatically. +
    How to test
    -
    Rule types
    -
    - This is a technical design rule and hence should be tested automatically. -
    @@ -554,23 +545,19 @@ An API is as good as the accompanying documentation. The documentation has to be
    This rule is included in the automatic tests 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
    +
    + This is a technical design rule and hence should be tested automatically. +
    How to test
    -
    Rule types
    -
    - This is a technical design rule and hence should be tested automatically. -
    @@ -638,25 +625,31 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil

    An example of a base path for an API with current version 1.0.2:

    https://api.example.org/v1/
    + 
    version: '1.0.2'
    + 
    servers:
+                  - description: test environment  
+                  url: https://api.test.example.org/v1/  
+                  - description: production environment  
+                  url: https://api.example.org/v1/  
+
    Implications
    This rule is included in the automatic tests 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
    +
    + This is a technical design rule and hence should be tested automatically. +
    How to test
    -
    Rule types
    -
    - This is a technical design rule and hence should be tested automatically. -
    @@ -699,21 +692,18 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    This rule is included in the automatic tests 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.
    -
    How to test
    -
    - -
    Rule types
    This is a technical design rule and hence should be tested automatically.
    +
    How to test
    +
    + +
    @@ -738,19 +728,17 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    This rule is included in the automatic tests 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
    +
    + This is a technical design rule and hence should be tested automatically. +
    How to test
    -
    Rule types
    -
    - This is a technical design rule and hence should be tested automatically. -
    From 2b103eb2bc09884dd4e718cc113bab8ee2b25494 Mon Sep 17 00:00:00 2001 From: strijm Date: Wed, 10 May 2023 18:38:12 +0200 Subject: [PATCH 07/13] Note en test cases API-03 aangepast. --- DesignRules.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 4d1b2d9..0fab50e 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -264,18 +264,33 @@ Although the REST architectural style does not impose a specific protocol, REST -

    The HTTP specification [[rfc7231]] and the later introduced PATCH method specification [[rfc5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS and TRACE. For the purpose of this design rule, these operations are left out of scope.

    -
    How to test
    +

    The HTTP specification [[rfc7231]] and the later introduced PATCH method specification [[rfc5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS, TRACE and CONNECT.
    + According to RFC 7231 4.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional.
    + In additon to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK etc.
    + If an optional HTTP request method is send to a server and the server does not support that HTTP method, a HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allowed header in the response as stated in RFC 7231 6.5.5.

    +
    How to test
    +

    Test case 1:

      -
    • Step 1: The API MUST meet the prerequisets to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
      • -
    • Step 2: Try non standard methods on the base url mentioned in the OAS file. The server MUST not respond to non-standard methods.
      • -
    +
  • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
    • +
  • Step 2: Send a HTTP GET or HEAD request to any of the endpoints mentioned in the OAS file. tandard methods on the base url mentioned in the OAS file. The server return a 200 OK response.
    • +
    Rule types
    This is a technical design rule and hence should be tested automatically.
    +

    Test case 2:

    +
    +
      +
    • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
      • +
    • Step 2: Send a request to the API with an optional HTTP method that is not supported by the API. The server MUST respond with a HTTP status code 405 Method Not Allowed. The response MUST contain an Allowed header with a list of supported methods for the target resource.
      • +
    +
    +
    Rule types
    +
    + This is a technical design rule and hence should be tested automatically. +
    From 32c196ca4e78638162e71f55b42ffcdb2d9c7c3f Mon Sep 17 00:00:00 2001 From: strijm Date: Wed, 10 May 2023 18:44:22 +0200 Subject: [PATCH 08/13] API-03 test case toegevoegd --- DesignRules.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 0fab50e..e3c6cd0 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -280,7 +280,18 @@ Although the REST architectural style does not impose a specific protocol, REST
    This is a technical design rule and hence should be tested automatically.
    -

    Test case 2:

    +

    Test case 2:

    +
    +
      +
    • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
      • +
    • Step 2: Send a request to the API with an optional HTTP method that is supported by the API. The server MUST respond with a HTTP status code other than 405 Method Not Allowed.
      • +
    +
    +
    Rule types
    +
    + This is a technical design rule and hence should be tested automatically. +
    +

    Test case 3:

    • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
      • From 29138cb75b8b3da6b55e784acc3a62f2c529e535 Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Thu, 11 May 2023 09:50:19 +0200 Subject: [PATCH 09/13] spelling --- DesignRules.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index e3c6cd0..8933e79 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -264,16 +264,16 @@ Although the REST architectural style does not impose a specific protocol, REST -

      The HTTP specification [[rfc7231]] and the later introduced PATCH method specification [[rfc5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS, TRACE and CONNECT.
      +

      The HTTP specification [[rfc7231]] and the later introduced PATCH method specification [[rfc5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS, TRACE, and CONNECT.
      According to RFC 7231 4.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional.
      - In additon to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK etc.
      - If an optional HTTP request method is send to a server and the server does not support that HTTP method, a HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allowed header in the response as stated in RFC 7231 6.5.5.

      + In additon to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK, etc.
      + If an optional HTTP request method is sent to a server and the server does not support that HTTP method, an HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allowed header in the response as stated in RFC 7231 6.5.5.

      How to test

      Test case 1:

        -
      • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
        • -
      • Step 2: Send a HTTP GET or HEAD request to any of the endpoints mentioned in the OAS file. tandard methods on the base url mentioned in the OAS file. The server return a 200 OK response.
        • +
      • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable, and paths are defined.
        • +
      • Step 2: Send an HTTP GET or HEAD request to any of the endpoints mentioned in the OAS file. tandard methods on the base url mentioned in the OAS file. The server return a 200 OK response.
      Rule types
      @@ -283,8 +283,8 @@ Although the REST architectural style does not impose a specific protocol, REST

      Test case 2:

        -
      • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
        • -
      • Step 2: Send a request to the API with an optional HTTP method that is supported by the API. The server MUST respond with a HTTP status code other than 405 Method Not Allowed.
        • +
      • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable, and paths are defined.
        • +
      • Step 2: Send a request to the API with an optional HTTP method that is supported by the API. The server MUST respond with an HTTP status code other than 405 Method Not Allowed.
      Rule types
      @@ -294,8 +294,8 @@ Although the REST architectural style does not impose a specific protocol, REST

      Test case 3:

        -
      • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
        • -
      • Step 2: Send a request to the API with an optional HTTP method that is not supported by the API. The server MUST respond with a HTTP status code 405 Method Not Allowed. The response MUST contain an Allowed header with a list of supported methods for the target resource.
        • +
      • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable, and paths are defined.
        • +
      • Step 2: Send a request to the API with an optional HTTP method that is not supported by the API. The server MUST respond with an HTTP status code 405 Method Not Allowed. The response MUST contain an Allowed header with a list of supported methods for the target resource.
      Rule types
      From c532a52bd66fab18da43238e7e7e50bd11e47d43 Mon Sep 17 00:00:00 2001 From: strijm Date: Fri, 12 May 2023 11:10:00 +0200 Subject: [PATCH 10/13] Review opmerkingen verwerkt --- DesignRules.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index e3c6cd0..9fae8c4 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -265,21 +265,18 @@ Although the REST architectural style does not impose a specific protocol, REST

      The HTTP specification [[rfc7231]] and the later introduced PATCH method specification [[rfc5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS, TRACE and CONNECT.
      + The OpenAPI Specification 3.x Path Item Object also supports these methods, except for CONNECT.
      According to RFC 7231 4.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional.
      - In additon to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK etc.
      - If an optional HTTP request method is send to a server and the server does not support that HTTP method, a HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allowed header in the response as stated in RFC 7231 6.5.5.

      + In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK etc.
      + If an optional HTTP request method is send to a server and the server does not support that HTTP method for the target resource, a HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allowed header in the response as stated in RFC 7231 6.5.5.

      How to test

      Test case 1:

      • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
        • -
      • Step 2: Send a HTTP GET or HEAD request to any of the endpoints mentioned in the OAS file. tandard methods on the base url mentioned in the OAS file. The server return a 200 OK response.
        • +
      • Step 2: Send a HTTP GET or HEAD request to any of the endpoints mentioned in the OAS file. The server MUST respond with a HTTP status code other than 405 Method Not Allowed.
      -
      Rule types
      -
      - This is a technical design rule and hence should be tested automatically. -

      Test case 2:

        @@ -287,10 +284,6 @@ Although the REST architectural style does not impose a specific protocol, REST
      • Step 2: Send a request to the API with an optional HTTP method that is supported by the API. The server MUST respond with a HTTP status code other than 405 Method Not Allowed.
      -
      Rule types
      -
      - This is a technical design rule and hence should be tested automatically. -

      Test case 3:

        From f8b2ad006a4c2d996227d01e9467673a65fd6ad8 Mon Sep 17 00:00:00 2001 From: strijm Date: Tue, 16 May 2023 14:11:27 +0200 Subject: [PATCH 11/13] Allowed -> Allow header --- DesignRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 54580e9..e71f7f2 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -268,7 +268,7 @@ Although the REST architectural style does not impose a specific protocol, REST The OpenAPI Specification 3.x Path Item Object also supports these methods, except for CONNECT.
        According to RFC 7231 4.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional.
        In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK, etc.
        - If an optional HTTP request method is sent to a server and the server does not support that HTTP method for the target resource, an HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allowed header in the response as stated in RFC 7231 6.5.5.

        + If an optional HTTP request method is sent to a server and the server does not support that HTTP method for the target resource, an HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allow header in the response as stated in RFC 7231 6.5.5.

        How to test

        Test case 1:

        @@ -288,7 +288,7 @@ Although the REST architectural style does not impose a specific protocol, REST
        • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable, and paths are defined.
          • -
        • Step 2: Send a request to the API with an optional HTTP method that is not supported by the API. The server MUST respond with an HTTP status code 405 Method Not Allowed. The response MUST contain an Allowed header with a list of supported methods for the target resource.
          • +
        • Step 2: Send a request to the API with an optional HTTP method that is not supported by the API. The server MUST respond with an HTTP status code 405 Method Not Allowed. The response MUST contain an Allow header with a list of supported methods for the target resource.
        Rule types
        From 0d37b0bd272fab460deb47d1cdcc68c735792775 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Tue, 5 Sep 2023 14:38:09 +0200 Subject: [PATCH 12/13] Update DesignRules.md Co-authored-by: Alexander Green --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index e71f7f2..3a6abd4 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -274,7 +274,7 @@ Although the REST architectural style does not impose a specific protocol, REST
        • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file is publicly available, parsable, all $refs are resolvable and paths are defined.
          • -
        • Step 2: Send an HTTP GET or HEAD request to any of the endpoints mentioned in the OAS file. The server MUST respond with a HTTP status code other than 405 Method Not Allowed.
          • +
        • Step 2: Send an HTTP GET or HEAD request to any of the endpoints with a definition of a GET operation mentioned in the OAS file. The server MUST respond with a HTTP status code other than 405 Method Not Allowed.

        Test case 2:

        From 58ddc099d8e8a2e24a241a3d2015f5469ea71049 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Tue, 5 Sep 2023 16:39:04 +0200 Subject: [PATCH 13/13] links ebijgewerkt en comments verwerkt --- DesignRules.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/DesignRules.md b/DesignRules.md index 3a6abd4..4c0025a 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -122,7 +122,7 @@ A resource describing a single thing is called a [singular resource](#dfn-singul
      Implications
      - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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
      @@ -500,7 +500,7 @@ An API is as good as the accompanying documentation. The documentation has to be
      Implications
      - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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
      @@ -562,7 +562,7 @@ An API is as good as the accompanying documentation. The documentation has to be
      Implications
      - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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
      @@ -573,7 +573,7 @@ An API is as good as the accompanying documentation. The documentation has to be
      • Step 1: The API MUST meet the prerequisets to be tested. These include that an OAS file (openapi.json) is publicly available, parsable, all $refs are resolvable and paths are defined.
      • Step 2: The openapi.yaml MAY be available. If available it MUST contain yaml, be readable and parsable.
        • -
      • Step 3: The openapi.yaml MUST describe the same API as the openapi.json.
        • +
      • Step 3: The openapi.yaml MUST contain the same OpenAPI Specification as the openapi.json.
      • Step 4: The CORS header Access-Control-Allow-Origin MUST allow all origins.
      @@ -655,7 +655,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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
    @@ -709,7 +709,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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
    @@ -745,7 +745,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    Implications
    - This rule is included in the automatic tests 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. + This rule is included in the automatic tests 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
    @@ -755,7 +755,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
    • Step 1: A request to the base url MUST give a response and include the header "API-Version".
      • -
    • Step 2: The response of the header MUST have a valid Semantic Versioning number.
      • +
    • Step 2: The value of the header "API-Version" MUST have a valid Semantic Versioning number.