From 764d0dcce0d51b7050fa353e361dccd0ccc6a764 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 13 May 2025 14:12:11 +0200 Subject: [PATCH 1/5] Voeg meer http methods toe aan core/http-methods Hiermee maken we het expliciet dat ook de HTTP methods die enkel (metadata) informatie ophalen toegestaan zijn. Deze methoden maken geen wijzigingen of lezen resources uit, maar kunnen gebruikt worden om informatie over het endpoint zelf uit te lezen. --- sections/designRules.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index ab3d941..581901f 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -135,7 +135,7 @@ Although the REST architectural style does not impose a specific protocol, REST
Statement
- Resources MUST be retrieved or manipulated using standard HTTP methods (GET/POST/PUT/PATCH/DELETE). + Resources MUST be retrieved or manipulated using standard HTTP methods (GET/POST/PUT/PATCH/DELETE). Resources SHOULD support HTTP methods that provide information without manipulating the underlying resources (HEAD/CONNECT/OPTIONS/TRACE).
Rationale
@@ -174,9 +174,29 @@ Although the REST architectural style does not impose a specific protocol, REST Delete Remove a resource with the given [=URI=]. + + HEAD + Read + Retrieve metadata of a resource representation for the given [=URI=]. + + + CONNECT + Read + Setup a tunnel for securely manipulating resources for the given [=URI=]. + + + OPTIONS + Read + Retrieve available operations on a resource for the given [=URI=]. + + + TRACE + Read + Retrieve an application-level loop-back of the original client request for the given [=URI=]. + -
The following table shows some examples of the use of standard HTTP methods: +
The following table shows some examples of the use of standard HTTP methods retrieving or manipulating resources: @@ -213,7 +233,7 @@ Although the REST architectural style does not impose a specific protocol, REST
-

The HTTP specification [[rfc9110]] offers 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 [[rfc9110]] offers a set of standard methods, where every method is designed with explicit semantics. The OpenAPI Specification 3.0 Path Item Object also supports these methods, except for CONNECT.
According to RFC 9110 9.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.
@@ -221,7 +241,7 @@ Although the REST architectural style does not impose a specific protocol, REST

How to test
- Analyse the OpenAPI Description to confirm all supported methods are either `post`, `put`, `get`, `delete`, or `patch`. + Analyse the OpenAPI Description to confirm all supported methods are either `get`, `post`, `put`, `patch`, `delete`, `head`, `options` or `trace`.
From 842b80eb4deaef1b6b9b40671a2dc8e922edf187 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Fri, 30 May 2025 10:14:04 +0200 Subject: [PATCH 2/5] Herstructureer HTTP methods sectie --- sections/designRules.md | 85 +++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 42 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 581901f..48c6a5e 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -135,11 +135,13 @@ Although the REST architectural style does not impose a specific protocol, REST
Statement
- Resources MUST be retrieved or manipulated using standard HTTP methods (GET/POST/PUT/PATCH/DELETE). Resources SHOULD support HTTP methods that provide information without manipulating the underlying resources (HEAD/CONNECT/OPTIONS/TRACE). + Resources MUST be retrieved or manipulated using standard HTTP methods (GET/POST/PUT/PATCH/DELETE). Resources MAY support HTTP methods that provide information without manipulating the underlying resources (including but not limited to HEAD/CONNECT/OPTIONS/TRACE).
Rationale
The HTTP specifications offer a set of standard methods, where every method is designed with explicit semantics. Adhering to the HTTP specification is crucial, since HTTP clients and middleware applications rely on standardized characteristics. +

According to RFC 9110 9.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional. +

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 9110 15.5.6. @@ -197,47 +199,46 @@ Although the REST architectural style does not impose a specific protocol, REST

The following table shows some examples of the use of standard HTTP methods retrieving or manipulating resources: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- RequestDescription
GET /rijksmonumentenRetrieves a list of national monuments.
GET /rijksmonumenten/12Retrieves an individual national monument.
POST /rijksmonumentenCreates a new national monument.
PUT /rijksmonumenten/12Modifies national monument #12 completely.
PATCH /rijksmonumenten/12Modifies national monument #12 partially.
DELETE /rijksmonumenten/12Deletes national monument #12.
-
-

The HTTP specification [[rfc9110]] offers a set of standard methods, where every method is designed with explicit semantics. - The OpenAPI Specification 3.0 Path Item Object also supports these methods, except for CONNECT.
- According to RFC 9110 9.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 Allow header in the response as stated in RFC 9110 15.5.6.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RequestDescription
GET /rijksmonumentenRetrieves a list of national monuments.
GET /rijksmonumenten/12Retrieves an individual national monument.
POST /rijksmonumentenCreates a new national monument.
PUT /rijksmonumenten/12Modifies national monument #12 completely.
PATCH /rijksmonumenten/12Modifies national monument #12 partially.
DELETE /rijksmonumenten/12Deletes national monument #12.
+ +
+

The HTTP specification [[rfc9110]] offers a set of standard methods, where every method is designed with explicit semantics. + The OpenAPI Specification 3.0 Path Item Object also supports these methods, except for CONNECT. +

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. +

How to test
From b7d743bb0f81df536d9f347b456e63a8c393f35e Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 23 Sep 2025 16:16:48 +0200 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Alexander Green --- sections/designRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 7daf42d..305184a 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -135,13 +135,13 @@ Although the REST architectural style does not impose a specific protocol, REST
Statement
- Resources MUST be retrieved or manipulated using standard HTTP methods (GET/POST/PUT/PATCH/DELETE). Resources MAY support HTTP methods that provide information without manipulating the underlying resources (including but not limited to HEAD/CONNECT/OPTIONS/TRACE). + An API MUST adhere to the HTTP method semantics defined in [rfc9110].
Rationale
The HTTP specifications offer a set of standard methods, where every method is designed with explicit semantics. Adhering to the HTTP specification is crucial, since HTTP clients and middleware applications rely on standardized characteristics.

According to RFC 9110 9.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional. -

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 9110 15.5.6. +

The set of methods allowed is determined per target resource. 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 9110 15.5.6. From 8175449189fe68f27f6bb2cb85375b90f87d46d0 Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Tue, 23 Sep 2025 16:22:45 +0200 Subject: [PATCH 4/5] http-methods nu `functional` --- sections/designRules.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 305184a..943678c 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -130,7 +130,7 @@ A resource that corresponds to a single conceptual entity is referred to as a [= Although the REST architectural style does not impose a specific protocol, REST APIs are typically implemented using HTTP [[rfc9110]]. -
+

Only apply standard HTTP methods

Statement
@@ -240,10 +240,6 @@ Although the REST architectural style does not impose a specific protocol, REST

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.

-
How to test
-
- Analyse the OpenAPI Description to confirm all supported methods are either `get`, `post`, `put`, `patch`, `delete`, `head`, `options` or `trace`. -
From 485abf7792ca5f9a7e0186b20a25709bcfb2fb9c Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 24 Sep 2025 09:53:03 +0200 Subject: [PATCH 5/5] Apply suggestions from code review --- sections/designRules.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 943678c..8b7b979 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -135,12 +135,11 @@ Although the REST architectural style does not impose a specific protocol, REST
Statement
- An API MUST adhere to the HTTP method semantics defined in [rfc9110]. + An API MUST adhere to the HTTP method semantics defined in [[rfc9110]].
Rationale
The HTTP specifications offer a set of standard methods, where every method is designed with explicit semantics. Adhering to the HTTP specification is crucial, since HTTP clients and middleware applications rely on standardized characteristics. -

According to RFC 9110 9.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional.

The set of methods allowed is determined per target resource. 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 9110 15.5.6.