Glossary idempotent #40369
Glossary idempotent #40369
Conversation
github-actions
bot
added
Content:Glossary
|
Preview URLs (comment last updated: 2025-07-16 08:13:34) |
There was a problem hiding this comment.
Hi @mb21, and thanks for the contribution!
I'm not an expert on this, but from what I've read on the subject, your addition seems like an oversimplification. PATCH can be idempotent or non-idempotent, depending on how your request is written to update the data you are modifying.
This thread contains some good examples: https://softwareengineering.stackexchange.com/questions/260818/why-patch-method-is-not-idempotent
Perhaps it'd be a good idea to include PATCH in a separate paragraph, along the lines of "{{HTTPMethod("PATCH")}} is a special case...",
|
From your link:
That's exactly right. And it's exactly the same for |
Yeah, I think it might be a good idea. I read the "That is the reason it is characterized as non-idempotent" line and thought, "well, that sounds a bit hand-wavy and vague". |
github-actions
bot
added
size/s
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
Updated! Let me know whether its clearer now. btw. actually the linked spec is quite well-written: https://httpwg.org/specs/rfc9110.html#idempotent.methods |
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
There was a problem hiding this comment.
This is great, thanks @mb21! I've included a few wording suggestions, but I think this is pretty close now.
|
|
||
| To be idempotent, only the state of the server is considered. The response returned by each request may differ: for example, the first call of a {{HTTPMethod("DELETE")}} will likely return a {{HTTPStatus("200")}}, while successive ones will likely return a {{HTTPStatus("404")}}. Another implication of {{HTTPMethod("DELETE")}} being idempotent is that developers should not implement RESTful APIs with a _delete last entry_ functionality using the `DELETE` method. | ||
| Idempotency, as defined by the HTTP specification, only considers the _intented_ effect of the client on the server: for example, a POST request intends to send data to the server, or a DELETE request intends to delete a resource on the server. A request with an idempotent method does not necessarily mean that the request does not have _any_ unique side effects: for example, the server may log every request with the time it was received. |
There was a problem hiding this comment.
| Idempotency, as defined by the HTTP specification, only considers the _intented_ effect of the client on the server: for example, a POST request intends to send data to the server, or a DELETE request intends to delete a resource on the server. A request with an idempotent method does not necessarily mean that the request does not have _any_ unique side effects: for example, the server may log every request with the time it was received. | |
| In the context of HTTP, idempotency only considers the _intended_ effect of the client on the server. For example, a POST request intends to send data to the server, whereas a DELETE request intends to delete a resource on the server. A request with an idempotent method does not necessarily mean that the request has _no_ unique side effects: For example, the server may log the time each request is received. |
You mentioned something to the effect of "defined by HTTP specification" twice, so I reworded one to get rid of repetition.
There was a problem hiding this comment.
I wouldn't mind the repetition, as it's kinda crucial to understand that we're only talking about the HTTP spec here.
I was actually looking into this for this chapter of a guide I'm writing: https://mastrojs.github.io/guide/http-forms-and-rest-apis/#client-side-fetching-a-rest-api and worded it there:
While the HTTP specification only talks about the effect on the server that the client intended, in practice it falls to the server to make sure the routes it exposes actually adhere to these semantics.
Not sure that's sufficiently clear? Because in practice, whether a request actually is idempotent or not (like whether actually it has the same effect whether it comes in multiple times or once) is entirely up to the server. But the HTTP spec didn't want to mandate that to servers, so it only talks about the effects the client intended. So they kinda say "btw FYI server: if a client sends you a GET, and since we're assuming the client adheres to the spec, then obviously the client intended an idempotent operation."
There was a problem hiding this comment.
I don't see the repetition as a deal breaker.
I like the sentence you've provided here, but it is a bit different in form to the original you provided. Maybe we could combine the two, maybe something like:
| Idempotency, as defined by the HTTP specification, only considers the _intented_ effect of the client on the server: for example, a POST request intends to send data to the server, or a DELETE request intends to delete a resource on the server. A request with an idempotent method does not necessarily mean that the request does not have _any_ unique side effects: for example, the server may log every request with the time it was received. | |
| The HTTP specification only defines idempotency in terms of the _intented_ effect of the client on the server. For example, a `POST` request intends to send data to the server, whereas a `DELETE` request intends to delete a resource on the server. In practice, it falls to the server to make sure the routes it exposes adhere to these semantics. Also, a request with an idempotent method does not necessarily mean that the request has _no_ unique side effects: For example, the server may log the time each request is received. |
WDYT?
There was a problem hiding this comment.
Ah, I committed that suggestion, only to realize it's kinda the same point as the last paragraph?
While servers are very much encouraged to adhere to the semantics laid out by the HTTP specification, the spec does not mandate it. Nothing is preventing a server in the wild from exposing a non-idempotent endpoint under an idempotent HTTP method, although clients may well be surprised.
There was a problem hiding this comment.
I did think about that, but I don't think it is making exactly the same point.
The first instance is saying that it is down to the server to adhere to those semantics.
The second instance is a follow-on — it says that servers are encouraged to adhere to the semantics, but nothing is forcing them to.
Tell you what, I'll edit it and move things around a bit, to make this link clearer, then I'll ask you what you think of the result.
There was a problem hiding this comment.
@mb21 OK, done. WDYT? I'm not sure how long it will take to propagate to the live preview, but you can view the changes immediately in the "Files changed" tab.
There was a problem hiding this comment.
nice! I just added one minor clarification, then I think it's good to go.
There was a problem hiding this comment.
Perfect, that looks good!
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Co-authored-by: Mauro Bieg <mb21@users.noreply.github.com>
There was a problem hiding this comment.
OK, we are ready to publish this one. Thanks so much for your work on this, @mb21 — this reads much better now.
Description
Clarify PATCH idempotency in body text
Motivation
Previously the paragraph mentioned PUT, DELETE and POST but curiously left out PATCH, which on a cursory reading could be interpreted as PATCH being idempotent (yes, the cursory reader was me).