Skip to content

Voeg meer http methods toe aan core/http-methods #223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
Open

Voeg meer http methods toe aan core/http-methods #223

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
764d0dc
Voeg meer http methods toe aan core/http-methods
TimvdLippe May 13, 2025
842b80e
Herstructureer HTTP methods sectie
TimvdLippe May 30, 2025
4d9dd50
Merge remote-tracking branch 'origin/develop' into pr-timvdlippe-opti…
TimvdLippe Aug 29, 2025
b7d743b
Apply suggestions from code review
TimvdLippe Sep 23, 2025
8175449
http-methods nu `functional`
sanderke Sep 23, 2025
485abf7
Apply suggestions from code review
TimvdLippe Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 64 additions & 48 deletions sections/designRules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]].

<span id="api-03"></span>
<div class="rule" id="/core/http-methods" data-type="technical">
<div class="rule" id="/core/http-methods" data-type="functional">
<p class="rulelab">Only apply standard HTTP methods</p>
<dl>
<dt>Statement</dt>
<dd>
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]].
</dd>
<dt>Rationale</dt>
<dd>
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.
<p>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 <code>405 Method Not Allowed</code> shall be returned and a list of allowed methods for the target resource shall be provided in the <code>Allow</code> header in the response as stated in <a href="https://www.rfc-editor.org/rfc/rfc9110#name-405-method-not-allowed">RFC 9110 15.5.6</a>.
<table>
<thead>
<tr>
Expand Down Expand Up @@ -174,54 +175,69 @@ Although the REST architectural style does not impose a specific protocol, REST
<td>Delete</td>
<td>Remove a resource with the given [=URI=].</td>
</tr>
<tr>
<td><code>HEAD</code></td>
<td>Read</td>
<td>Retrieve metadata of a resource representation for the given [=URI=].</td>
</tr>
<tr>
<td><code>CONNECT</code></td>
<td>Read</td>
<td>Setup a tunnel for securely manipulating resources for the given [=URI=].</td>
</tr>
<tr>
<td><code>OPTIONS</code></td>
<td>Read</td>
<td>Retrieve available operations on a resource for the given [=URI=].</td>
</tr>
<tr>
<td><code>TRACE</code></td>
<td>Read</td>
<td>Retrieve an application-level loop-back of the original client request for the given [=URI=].</td>
</tr>
</tbody>
</table>
<div class="example">The following table shows some examples of the use of standard HTTP methods:
<table>
<thead>
<tr>
<th scope="col">
Request</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET /rijksmonumenten</code></td>
<td>Retrieves a list of national monuments.</td>
</tr>
<tr>
<td><code>GET /rijksmonumenten/12</code></td>
<td>Retrieves an individual national monument.</td>
</tr>
<tr>
<td><code>POST /rijksmonumenten</code></td>
<td>Creates a new national monument.</td>
</tr>
<tr>
<td><code>PUT /rijksmonumenten/12</code></td>
<td>Modifies national monument #12 completely.</td>
</tr>
<tr>
<td><code>PATCH /rijksmonumenten/12</code></td>
<td>Modifies national monument #12 partially.</td>
</tr>
<tr>
<td><code>DELETE /rijksmonumenten/12</code></td>
<td>Deletes national monument #12.</td>
</tr>
</tbody>
</table>
</div>
<p class="note">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. <code>HEAD</code>, <code>OPTIONS</code>, <code>TRACE</code>, and <code>CONNECT</code>.<br>
The OpenAPI Specification 3.0 <a href="https://spec.openapis.org/oas/v3.0.1#path-item-object">Path Item Object</a> also supports these methods, except for <code>CONNECT</code>.<br>
According to <a href="https://www.rfc-editor.org/rfc/rfc9110#name-overview">RFC 9110 9.1</a> the <code>GET</code> and <code>HEAD</code> HTTP methods MUST be supported by the server, all other methods are optional.<br>
In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. <code>PROPFIND</code>, <code>COPY</code>, <code>PURGE</code>, <code>VIEW</code>, <code>LINK</code>, <code>UNLINK</code>, <code>LOCK</code>, <code>UNLOCK</code>, etc.<br>
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 <code>405 Method Not Allowed</code> shall be returned and a list of allowed methods for the target resource shall be provided in the <code>Allow</code> header in the response as stated in <a href="https://www.rfc-editor.org/rfc/rfc9110#name-405-method-not-allowed">RFC 9110 15.5.6</a>.</p>
</dd>
<dt>How to test</dt>
<dd>
Analyse the OpenAPI Description to confirm all supported methods are either `post`, `put`, `get`, `delete`, or `patch`.
<div class="example">The following table shows some examples of the use of standard HTTP methods retrieving or manipulating resources:
<table>
<thead>
<tr>
<th scope="col">Request</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET /rijksmonumenten</code></td>
<td>Retrieves a list of national monuments.</td>
</tr>
<tr>
<td><code>GET /rijksmonumenten/12</code></td>
<td>Retrieves an individual national monument.</td>
</tr>
<tr>
<td><code>POST /rijksmonumenten</code></td>
<td>Creates a new national monument.</td>
</tr>
<tr>
<td><code>PUT /rijksmonumenten/12</code></td>
<td>Modifies national monument #12 completely.</td>
</tr>
<tr>
<td><code>PATCH /rijksmonumenten/12</code></td>
<td>Modifies national monument #12 partially.</td>
</tr>
<tr>
<td><code>DELETE /rijksmonumenten/12</code></td>
<td>Deletes national monument #12.</td>
</tr>
</tbody>
</table>
</div>
<div class="note">
<p>The HTTP specification [[rfc9110]] offers a set of standard methods, where every method is designed with explicit semantics.
The OpenAPI Specification 3.0 <a href="https://spec.openapis.org/oas/v3.0.1#path-item-object">Path Item Object</a> also supports these methods, except for <code>CONNECT</code>.
<p>In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. <code>PROPFIND</code>, <code>COPY</code>, <code>PURGE</code>, <code>VIEW</code>, <code>LINK</code>, <code>UNLINK</code>, <code>LOCK</code>, <code>UNLOCK</code>, etc.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. <code>PROPFIND</code>, <code>COPY</code>, <code>PURGE</code>, <code>VIEW</code>, <code>LINK</code>, <code>UNLINK</code>, <code>LOCK</code>, <code>UNLOCK</code>, etc.
<p>In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. <code>PROPFIND</code>, <code>COPY</code>, <code>PURGE</code>, <code>VIEW</code>, <code>LINK</code>, <code>UNLINK</code>, <code>LOCK</code>, <code>UNLOCK</code>, etc. Additional methods MAY be documented using OpenAPI 3.2 while preserving these semantics defined in [rfc9110].

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ik weet niet of we hier al kunnen verwijzen naar 3.2. Misschien kunnen we dit in een niet-normatieve noot toevoegen van "dit komt er in de toekomst aan"?

</div>
</dd>
</dl>
</div>
Expand Down
Loading