@oblomov the semantic argument might be that GET is appropriate for when you want to refer to a query itself, for example using /search?bananas to search for "bananas". but the problems with GET are numerous:

- query components are often logged, while request bodies are not
- query components are limited in how complex they can get -- it's not easy to represent arrays, maps, hierarchical data, and so on
- search may be an expensive request, so better to not allow any old browser to do it

@oblomov well POST is "do something" not necessarily "create something". rfc-editor.org/rfc/rfc9110.htm…

> process the representation enclosed in the request according to the resource's own specific semantics

imo "take this request, parse some params out of it, then perform the action" is a valid way of thinking about search.

as for GET,

> requests transfer of a current selected representation for the target resource

is often but not always appropriate. depends on if you see results as a resource.

@oblomov

and that's what it really comes down to imo -- the use of a query component fundamentally alters the identity, you are asking for a different resource when you append the query component. /search and /search?query are different resources.

@oblomov I'd add one additional benefit: they're infinitely easier to debug and test.

At least it's pretty common practice as I recall in Java EE to make an HttpServlet, generate doGet/doPost, and have doPost just call doGet, or vice versa.

Then GET URL calls let you diagnose what's being passed to which query parameter.

@Charrondev @AT1ST @oblomov now imagine this is all exposed prominently to users, some of whom know how to edit an address bar. :p

this is why i said it’s akin to url hacking upthread. the url hacking only works if the query string behaves as you expect it to.

more to the point of fedi: impls need to be aware that they might GET one id but the response contains a different (canonized) id. unfortunately this might very well break existing fedi implementations who are exceptionally brittle…

@AT1ST @oblomov For example, I might have GET /api/discussions which lists resources. I likely want to support a mechanism for that paginating, sorting, and filtering. For this I document query parameters for the purpose.

The resources themself will have a canonical URL generated by the server. In my case /discussions/3131/some-arbitrary-slug/p1

This time the pagination is encoded in the URL as well as arbitrary data.

@AT1ST @oblomov there’s no fixed standards for bodies either though or paths. Data can be encoded in paths in arbitrary ways (including query parameters).

The client and server must agree on a serialization format in both cases. For bodies I typically use JSON. For paths the format is documented and generated by the application when possible.

@Charrondev @AT1ST @oblomov right, but arbitrary paths/etc generally don’t break the opaqueness

let me put it this way. the expectation some (many?) people might have is that the query string can be delimited by & and reordered without changing the response. but it’s wrong to say that it doesn’t change the *identity*. it’s as wrong as expecting /foo/bar to be the same as /bar/foo — there is a common understanding that the path component is opaque, but we can’t say the same for a query component

@AT1ST @oblomov well one massive negative to exposing your search as POST only is they your edge network can’t cache similar responses.

The query normalization doesn’t matter because the web app will ensure queries are in a consistent order.

As an example if you do /api/user/search?name=a* (such as in a mention lookup) then we can cache this response on our edge.

Now technically you could also cache a POST, but most edge networks can’t cache by body.

@Charrondev @AT1ST @oblomov is /search?query=foo&limit=10 the same resource as /search?limit=10&query=foo to you? or is it two different resources with the same representation?

functionally it is about resource identity. calling POST /search with {“query”: “foo”, “limit”: 10} keeps it clear that the resource is /search. putting request params in the identity string is mixing concerns. this matters a lot more when designing protocols where uri equivalence is important. query normalization sucks.

@AT1ST @oblomov and how is it any more “right” to obscure the thing that was searched for in your logs, to the user, and when sharing links?

I definitely see the case for a search API endpoint (not exposed to the user) being a POST (and elastic search does this), but our user facing search page is definitely a GET. Modified filters and the query text end up as query parameters.

Just because full text search is suddenly involved why is GET no longer appropriate?