[pcthrowaway]

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]

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.

[Veserv]

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]

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.

[Veserv]

Client intent is distinct from server interpretation. Distinguishing these is important when defining protocols/interfaces.

A client can blindly PUT a endpoint that does not support PUT, only GET. In the cold connection case where does this fail? The client succeeds at serializing the message, the client succeeds at sending it, the message gets successfully received, and only upon examining the message itself does the server know it should not follow the client intent. This is the same behavior as if the client sent garbled nonsense.

The key here is that it is the server demanding certain message structures. The client is free to send whatever, it just only succeeds if it sends something the server will accept. The server distinguishes, but to the client it is no different from sending any other opaque blob of data. This is thus just a server-constraint, the endpoint is GET-only. To use this website/HTTP interface, the client needs to know that.

It will need to know to format the message correctly, but that derives from knowledge of the documented server interface. If you had just a direct connection with no intermediary participants, then you could trivially swap out HTTP for any other transport protocol without a loss of functionality or behavior. That points to there being no reason to syntactically distinguish on the client to server leg of the transport protocol. However, you still have GET endpoint behavior since that is actually preserved across transport changes, so that is the important class of behavior to define.

The opposing point here is that if you do have intermediarys then they may care about the message format and you may need to syntactically distinguish them. I suspect this is less beneficial than a simpler and more flexible, yet precise transport format.

Basically, we should prefer simple, flexible transport formats and push interpretation (and thus behavior) out to the endpoints which actually have enough context to know the true properties of what they are doing.

[ahtihn]

> The fact that this endpoint guarantees QUERY behavior is just part of the documented server interface

And how do you communicate this behavior to the client (and any other infrastructure in-between) in a machine-readable way?

[LoganDark]

PUT is the idempotent one. POST typically performs an action; PUT just creates-or-updates.