3 ms·

I'm confused - wouldn't idempotent POST be PUT? Isn't the proposed QUERY for fetching semantics?

Veserv 11mo ago
The existing mechanism to get QUERY semantics is a POST that encodes the “fetch parameters” in the body and the response contains the fetched values. You then out-of-band document that this specific use of a fetching POST is idempotent. This is literally expressed in the document in section 1: Introduction. They just want to take that POST request and replace the word POST with QUERY which also means the server is intended to assure the request is idempotent instead of needing that documented out-of-band.
johncolanduoni 11mo ago
For some reason the RFC focuses on idempotency, but then says it's explicitly intended for enabling caching semantics. Caching a query that mutates visible state doesn't really make sense, and like you point out if you just want idempotent modifications PUT already has the relevant semantics. I guess we haven't learned our lesson from making the original HTTP semantics super squishy.
- dragonwriter 11mo ago
  > For some reason the RFC focuses on idempotency, It focuses on a bit more on safety, which is why every mention of it the proposed method having the "idempotent" property is immediately preceded (in most cases in the same sentence) by description of it having the "safe" property.
pcthrowaway 11mo ago
I think the idea is that POST creates a record (and in theory fails if that record already exists). I guess the commenter above is saying that if you inverted that (fail when the record doesn't exist, return the record if it does) it would be similar to QUERY? Not sure if I agree with that, but PUT's return semantics are a bit vague.. it often returns partial or combined records, or just a 200 OK (with or without a response body), or 204 No Content for unchanged records (with or without a response body) It's clear what POST returns, so... perhaps QUERY is more similar to it in that sense?
- johncolanduoni 11mo ago
  Whatever the original intent was, POST definitely does not return a new record consistently in most actual APIs. It's frequently used for actions that don't conceptually create anything at all.
- LoganDark 11mo ago
  PUT is the idempotent one. POST typically performs an action; PUT just creates-or-updates.
- Veserv 11mo ago
  No, I was referencing the example in the article in literally the very first section showing and explaining how POST endpoints are used for fetching data when GET endpoints are too limited. This is literally their motivating impetus for the QUERY request type. When considered abstractly, POST is just a request body and a response body. This is obviously powerful enough to define any behavior you want; it is just a channel flowing a nearly arbitrary amount of opaque data between the client and server. However, this kind of sucks because it does not define or constrain the behavior of the client or the server. QUERY says that the server is intended to interpret the request body as fetch parameters and return a response body as the fetched data, and further guarantee that the fetch is safe/idempotent. This is very useful. My disagreement is that there is no good reason for the client request format to care. You should “POST” to a “QUERY” endpoint. The fact that this endpoint guarantees QUERY behavior is just part of the documented server interface in the same way that certain endpoints may not support PUT. This is a server constraint, not a client constraint so should not change the client transport format. Requiring a new Client request type to agree with a new Server endpoint type is just unnecessary and mixes up server versus client responsibility and interface design.
  - happytoexplain 11mo ago
    I'm not following how this is different from not even using HTTP verbs. We didn't define them because it's the only possible way to declare client intent. They're cognitively useful for setting expectations, organization, announcing abilities, separation of concerns, etc. The fact that POST is today sometimes used in practice as a safe+idempotent query (i.e. a GET with a body) seems like the black sheep violating those useful qualities.
deleted 11mo ago
[deleted]
dragonwriter 11mo ago
Essentially correct, QUERY is safe, like GET, not merely idempotent, like PUT. Safety implies idempotence, but not vice versa.
- simonkagedal 11mo ago
  Does “safe” here mean just “non-mutating”?
  - dragonwriter 11mo ago
    No, it doesn't just mean that (it does mean non-mutating from the point of view of the client and in regard to the target resource, but the essential meaning involves more than that and it is more subtle than simply “non-mutating”.) The specific definition is in the HTTP spec, and I don't think I can describe it more concisely without losing important information necessary for really understanding it. https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1 https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1
  - paulddraper 11mo ago
    Yes.

Veserv 11mo ago

The existing mechanism to get QUERY semantics is a POST that encodes the “fetch parameters” in the body and the response contains the fetched values. You then out-of-band document that this specific use of a fetching POST is idempotent. This is literally expressed in the document in section 1: Introduction. They just want to take that POST request and replace the word POST with QUERY which also means the server is intended to assure the request is idempotent instead of needing that documented out-of-band.

johncolanduoni 11mo ago

For some reason the RFC focuses on idempotency, but then says it's explicitly intended for enabling caching semantics. Caching a query that mutates visible state doesn't really make sense, and like you point out if you just want idempotent modifications PUT already has the relevant semantics. I guess we haven't learned our lesson from making the original HTTP semantics super squishy.

dragonwriter 11mo ago
> For some reason the RFC focuses on idempotency, It focuses on a bit more on safety, which is why every mention of it the proposed method having the "idempotent" property is immediately preceded (in most cases in the same sentence) by description of it having the "safe" property.

pcthrowaway 11mo ago

I think the idea is that POST creates a record (and in theory fails if that record already exists). I guess the commenter above is saying that if you inverted that (fail when the record doesn't exist, return the record if it does) it would be similar to QUERY? Not sure if I agree with that, but PUT's return semantics are a bit vague.. it often returns partial or combined records, or just a 200 OK (with or without a response body), or 204 No Content for unchanged records (with or without a response body) It's clear what POST returns, so... perhaps QUERY is more similar to it in that sense?

johncolanduoni 11mo ago
Whatever the original intent was, POST definitely does not return a new record consistently in most actual APIs. It's frequently used for actions that don't conceptually create anything at all.
LoganDark 11mo ago
PUT is the idempotent one. POST typically performs an action; PUT just creates-or-updates.
Veserv 11mo ago
No, I was referencing the example in the article in literally the very first section showing and explaining how POST endpoints are used for fetching data when GET endpoints are too limited. This is literally their motivating impetus for the QUERY request type. When considered abstractly, POST is just a request body and a response body. This is obviously powerful enough to define any behavior you want; it is just a channel flowing a nearly arbitrary amount of opaque data between the client and server. However, this kind of sucks because it does not define or constrain the behavior of the client or the server. QUERY says that the server is intended to interpret the request body as fetch parameters and return a response body as the fetched data, and further guarantee that the fetch is safe/idempotent. This is very useful. My disagreement is that there is no good reason for the client request format to care. You should “POST” to a “QUERY” endpoint. The fact that this endpoint guarantees QUERY behavior is just part of the documented server interface in the same way that certain endpoints may not support PUT. This is a server constraint, not a client constraint so should not change the client transport format. Requiring a new Client request type to agree with a new Server endpoint type is just unnecessary and mixes up server versus client responsibility and interface design.
- happytoexplain 11mo ago
  I'm not following how this is different from not even using HTTP verbs. We didn't define them because it's the only possible way to declare client intent. They're cognitively useful for setting expectations, organization, announcing abilities, separation of concerns, etc. The fact that POST is today sometimes used in practice as a safe+idempotent query (i.e. a GET with a body) seems like the black sheep violating those useful qualities.

deleted 11mo ago

[deleted]

dragonwriter 11mo ago

Essentially correct, QUERY is safe, like GET, not merely idempotent, like PUT. Safety implies idempotence, but not vice versa.

simonkagedal 11mo ago
Does “safe” here mean just “non-mutating”?
- dragonwriter 11mo ago
  No, it doesn't just mean that (it does mean non-mutating from the point of view of the client and in regard to the target resource, but the essential meaning involves more than that and it is more subtle than simply “non-mutating”.) The specific definition is in the HTTP spec, and I don't think I can describe it more concisely without losing important information necessary for really understanding it. https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1 https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1
- paulddraper 11mo ago
  Yes.