"URI for the Request vs. URI for the Result" - I am not sure which parts are requests and which parts are responses. So then I don't understand what exactly happens and when you wrote
GET /saved-queries/42
→ The server re-executes the original SQL query
→ You get fresh results
I could use a more detailed example.
this part
We also get an evolution in REST API design. Instead of:
GET /api/users/active
GET /api/users/inactive
GET /api/users/premium
You now have:
QUERY /api/users
👨🎓About Me :
Creative, with a real critical mind and a real desire to continuously improve myself.
Passionate about this field, I love to share and discuss about it and learn more.
Thanks for your feedback! Those are good questions. Looking back, I realize these two sections could have used a bit more clarification.
1. URI for the Request vs. URI for the Result
The distinction is actually quite simple once you separate the two concepts:
URI for the Result points to the result of a query, in other words, the data returned at a specific point in time.
URI for the Request points to the query definition itself.
For example, imagine you want to retrieve all paid orders with a total greater than $100. The server executes the query and returns the matching results.
If the server also stores the query definition, it can provide you with a URI associated with that query. You can then reuse that URI later to ask the server to execute the exact same query again, but against the latest data.
That's what I was trying to illustrate with GET /saved-queries/42: you're not necessarily retrieving the same results as before. You're asking the server to re-execute the saved query.
2. Evolution in REST API design
The idea here is to avoid creating multiple endpoints for different filters.
Instead of having one endpoint for active users, another for inactive users, and another for premium users, you could have a single generic endpoint:
QUERY/api/users
The request body simply describes what you're looking for (active users, premium users, etc.). The server interprets those criteria and returns the matching users.
Basically, you're separating the search endpoint from the search criteria themselves.
I'm planning to write a follow-up article covering a concrete use case to demonstrate what we can actually build with QUERY and explore its possibilities in a real-world scenario.
Thanks again for taking the time to share your questions!
Web Dev full-stack [LAMP] since 2005, but much heavier on the JS stuff these days.
Jack of all Stacks, Master of some.
Always looking to learn new things. Always glad to help out, just ask.
Location
Atlanta, GA
Education
B.S. in Biochemistry 2004, M.S. in Computer Information Systems 2007
You can do everything with POST alone. You can retrieve data, create new entities, update stuff or delete them. Hence I suggest we remove all HTTP verbs including POST, since it can be implied. Problem solved.
On the other hand we may want some semantics, so things clearly show their intent from afar without having to delve into codebase or descriptions. That's why any of my OAS, have very few POST requests, one for every entity that allows the client creation. Then I also seldom use PUT, because there are rare cases, where I intend to update an entity by replacing it whole. I used to create a lot of update forms where you'd change as many values as wanted in GUI and then explicitly PUT them by pressing the Save button. Nowadays, I auto-save most inputs on blur (the opposite of focus), so updates are way more surgical. Hence most of my updates use PATCH request to update existing entity's properties or whatever state is in question. DELETE is self explanatory in all its glory. Admittedly I have never gotten around to try to deeply understand the use cases for HEAD, CONNECT, OPTIONS and TRACE for me, so all that's left is GET. I love using it without query params, but when those are needed, I always disliked how GET is the odd one out of all the HTTP verbs. That is all to say, I am thrilled for QUERY to have become a new standard for this usecase.
As for you, it's simple... Just don't use it.
Edit: I by no means mean that QUERY should replace GET+queryParams everywhere. While it will do so in my OASs, I think it is absolutely essential to keep it, so we can for example share links with already filtered or ordered results.
Web Dev full-stack [LAMP] since 2005, but much heavier on the JS stuff these days.
Jack of all Stacks, Master of some.
Always looking to learn new things. Always glad to help out, just ask.
Location
Atlanta, GA
Education
B.S. in Biochemistry 2004, M.S. in Computer Information Systems 2007
it's a good response, and personally i won't use it, i'll continue logging what my POST requests do and returning errors when the server fails and error messages when the request cannot be fullfilled.
Web Dev full-stack [LAMP] since 2005, but much heavier on the JS stuff these days.
Jack of all Stacks, Master of some.
Always looking to learn new things. Always glad to help out, just ask.
Location
Atlanta, GA
Education
B.S. in Biochemistry 2004, M.S. in Computer Information Systems 2007
lol... what do you call "wrong-side driving accidents" ?
Like, someone makes a choice to do the wrong thing.
Yes, allowing duplicates to happen is bad code handling, it's human error.
On that same note, in the future you'll equate wrong-side driving with "they used POST instead of Query"... which is no different than me saying "they should block duplication in their POSTs" ...which again brings me to Query not being necessary.
which is no different than me saying "they should block duplication in their POSTs"
It is different though. Using POST where QUERY fits is the wrong-side driving. "They should block duplication in their POSTs" is telling people to drive carefully on the wrong side.
Allowing duplicates with POST is not someone choosing to do the wrong thing. Picking POST for something that should have been retry-safe is. POST is defined as non-idempotent, so nothing upstream is allowed to assume repeating it is safe. That's not a bug you patch, that's the rule.
And such fixes work only within systems you can control. They hold up only until you ship a public API, or put it behind a CDN. The CDN won't cache your response. Or, a browser won't retry a failed call. A load balancer assumes replaying it might double-charge the user, so it won't. All correct behaviour, given what you told them. There are real implementations out there making decisions about your API based on established rules, and none of them can see your homemade one. That's the human error, caused by choosing to do the wrong thing.
👨🎓About Me :
Creative, with a real critical mind and a real desire to continuously improve myself.
Passionate about this field, I love to share and discuss about it and learn more.
👨🎓About Me :
Creative, with a real critical mind and a real desire to continuously improve myself.
Passionate about this field, I love to share and discuss about it and learn more.
👨🎓About Me :
Creative, with a real critical mind and a real desire to continuously improve myself.
Passionate about this field, I love to share and discuss about it and learn more.
But the spec actually lands on the opposite conclusion: QUERY is the more cache-friendly of the two.
RFC 10008 says it directly: "The response to a QUERY method is cacheable; a cache MAY use it to satisfy subsequent QUERY requests." The one twist is that the cache key must incorporate the request body, not just the URI but that's the cache/proxy's job, not something your API has to build.
The POST + GET pattern does work, but it's not "more" cacheable — it's less cacheable out of the box, and it costs you:
Two round-trips (create the query, then fetch by id).
Server-side state you persist the query, mint a query_id, and manage its lifecycle.
And what you cache there is the frozen result behind that id, not the query itself.
That's exactly the Content-Location (URI of the result) vs Location (URI of the query). QUERY gives you both for free: the server can return a Location so you can replay the same query later with a plain GET no body resend and it re-runs against fresh data. POST + GET only gets you the frozen-result URI, and only if you build the storage for it.
So POST caches a static snapshot at the price of extra state and an extra round-trip. QUERY makes the read operation itself safe, idempotent, and cacheable which is the whole gap it was standardized to fill.
👨🎓About Me :
Creative, with a real critical mind and a real desire to continuously improve myself.
Passionate about this field, I love to share and discuss about it and learn more.
great information, thank you!
However I dont understand these two parts:
I could use a more detailed example.
not sure what the QUERY should yield.
Thanks for your feedback! Those are good questions. Looking back, I realize these two sections could have used a bit more clarification.
1. URI for the Request vs. URI for the Result
The distinction is actually quite simple once you separate the two concepts:
For example, imagine you want to retrieve all paid orders with a total greater than $100. The server executes the query and returns the matching results.
If the server also stores the query definition, it can provide you with a URI associated with that query. You can then reuse that URI later to ask the server to execute the exact same query again, but against the latest data.
That's what I was trying to illustrate with
GET /saved-queries/42: you're not necessarily retrieving the same results as before. You're asking the server to re-execute the saved query.2. Evolution in REST API design
The idea here is to avoid creating multiple endpoints for different filters.
Instead of having one endpoint for active users, another for inactive users, and another for premium users, you could have a single generic endpoint:
The request body simply describes what you're looking for (active users, premium users, etc.). The server interprets those criteria and returns the matching users.
Basically, you're separating the search endpoint from the search criteria themselves.
I'm planning to write a follow-up article covering a concrete use case to demonstrate what we can actually build with QUERY and explore its possibilities in a real-world scenario.
Thanks again for taking the time to share your questions!
ok, i don't see the reasoning for it.
We also have PUT and DELETE that no one ever uses since you can pretty much accomplish all of them with POST just the same.
It just feels like one more thing only some devs will use, and newbies will get confused by and in the end we'll just be doing GET and POST anyway.
Just my 2 cents.
You can do everything with POST alone. You can retrieve data, create new entities, update stuff or delete them. Hence I suggest we remove all HTTP verbs including POST, since it can be implied. Problem solved.
On the other hand we may want some semantics, so things clearly show their intent from afar without having to delve into codebase or descriptions. That's why any of my OAS, have very few POST requests, one for every entity that allows the client creation. Then I also seldom use PUT, because there are rare cases, where I intend to update an entity by replacing it whole. I used to create a lot of update forms where you'd change as many values as wanted in GUI and then explicitly PUT them by pressing the Save button. Nowadays, I auto-save most inputs on blur (the opposite of focus), so updates are way more surgical. Hence most of my updates use PATCH request to update existing entity's properties or whatever state is in question. DELETE is self explanatory in all its glory. Admittedly I have never gotten around to try to deeply understand the use cases for HEAD, CONNECT, OPTIONS and TRACE for me, so all that's left is GET. I love using it without query params, but when those are needed, I always disliked how GET is the odd one out of all the HTTP verbs. That is all to say, I am thrilled for QUERY to have become a new standard for this usecase.
As for you, it's simple... Just don't use it.
Edit: I by no means mean that QUERY should replace GET+queryParams everywhere. While it will do so in my OASs, I think it is absolutely essential to keep it, so we can for example share links with already filtered or ordered results.
it's a good response, and personally i won't use it, i'll continue logging what my POST requests do and returning errors when the server fails and error messages when the request cannot be fullfilled.
The analogy I've always used for this kind of reasoning is that, yes, you can drive on the wrong side of the road – doesn't mean you should.
"POSTs creating duplicate entries is just bad code handling", is like saying wrong-side driving causing accidents is just poor driving skills.
You may want to read: developer.mozilla.org/en-US/docs/W...
lol... what do you call "wrong-side driving accidents" ?
Like, someone makes a choice to do the wrong thing.
Yes, allowing duplicates to happen is bad code handling, it's human error.
On that same note, in the future you'll equate wrong-side driving with "they used POST instead of Query"... which is no different than me saying "they should block duplication in their POSTs" ...which again brings me to Query not being necessary.
It is different though. Using POST where QUERY fits is the wrong-side driving. "They should block duplication in their POSTs" is telling people to drive carefully on the wrong side.
Allowing duplicates with POST is not someone choosing to do the wrong thing. Picking POST for something that should have been retry-safe is. POST is defined as non-idempotent, so nothing upstream is allowed to assume repeating it is safe. That's not a bug you patch, that's the rule.
And such fixes work only within systems you can control. They hold up only until you ship a public API, or put it behind a CDN. The CDN won't cache your response. Or, a browser won't retry a failed call. A load balancer assumes replaying it might double-charge the user, so it won't. All correct behaviour, given what you told them. There are real implementations out there making decisions about your API based on established rules, and none of them can see your homemade one. That's the human error, caused by choosing to do the wrong thing.
tks for dropping.
Thanks for your comment !
Thank you mhn i needed the info
It's a pleasure, thanks for your comment !
POST /query
very big queryGET /query/
query_id_i_just_created(or)
QUERY /query
very big querywhich would be cache friendly, i think the former.🤷
Good question, thank you for your comments.
But the spec actually lands on the opposite conclusion: QUERY is the more cache-friendly of the two.
RFC 10008 says it directly: "The response to a QUERY method is cacheable; a cache MAY use it to satisfy subsequent QUERY requests." The one twist is that the cache key must incorporate the request body, not just the URI but that's the cache/proxy's job, not something your API has to build.
The POST + GET pattern does work, but it's not "more" cacheable — it's less cacheable out of the box, and it costs you:
query_id, and manage its lifecycle.And what you cache there is the frozen result behind that id, not the query itself.
That's exactly the Content-Location (URI of the result) vs Location (URI of the query). QUERY gives you both for free: the server can return a Location so you can replay the same query later with a plain GET no body resend and it re-runs against fresh data. POST + GET only gets you the frozen-result URI, and only if you build the storage for it.
So POST caches a static snapshot at the price of extra state and an extra round-trip. QUERY makes the read operation itself safe, idempotent, and cacheable which is the whole gap it was standardized to fill.
Must Read Article
Thanks for your comment !