diff --git a/sections/designRules.md b/sections/designRules.md index 95403e7..8b7b979 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -130,16 +130,17 @@ 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
- Resources MUST be retrieved or manipulated using standard HTTP methods (GET/POST/PUT/PATCH/DELETE). + 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. +

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. @@ -174,54 +175,69 @@ Although the REST architectural style does not impose a specific protocol, REST + + + + + + + + + + + + + + + + + + + +
Delete Remove a resource with the given [=URI=].
HEADReadRetrieve metadata of a resource representation for the given [=URI=].
CONNECTReadSetup a tunnel for securely manipulating resources for the given [=URI=].
OPTIONSReadRetrieve available operations on a resource for the given [=URI=].
TRACEReadRetrieve 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: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- 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. HTTP also defines other methods, e.g. HEAD, OPTIONS, TRACE, and CONNECT.
- 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.

-
-
How to test
-
- Analyse the OpenAPI Description to confirm all supported methods are either `post`, `put`, `get`, `delete`, or `patch`. +
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. +

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