Allowing POST as fallback for GET when query would exceed maximum length of URL

A typical search query looks something like GET example.com/entity/search?q=John If we want to add some filtering to this endpoint, we could for example add ...&filter= followed by a URL encoding of something like { "and": [ { "equals": { "field": "lastName", "value": "Smith" } }, { "greaterThan": { "field": "age", "value": 20 } } ] } In this case however, the query string may become arbitrarily long, and for technical reasons you shouldn't really exceed ~2000 characters. For this reason, some people suggest using POST even though it's arguably not an ideal choice from a semantical point of view. So, I'm considering allowing both GET and POST: For queries that fit in a URL: Use GET for clarity, ease of debugging, and semantically accurate requests. For queries that exceed maximum length of a URL: Use POST and pass query / filtering as body. Apart from requiring slightly more code and documentation, I can't really see any drawbacks. OTOH I don't think I've stumbled across this approach when reading API documentation. My questions: Is there any prior art of such solution in a public "widely available" API? Are there any drawbacks I'm missing?

Mar 14, 2025 - 18:29

A typical search query looks something like

GET example.com/entity/search?q=John

If we want to add some filtering to this endpoint, we could for example add ...&filter= followed by a URL encoding of something like

{
  "and": [
    {
      "equals": {
        "field": "lastName",
        "value": "Smith"
      }
    },
    {
      "greaterThan": {
        "field": "age",
        "value": 20
      }
    }
  ]
}

In this case however, the query string may become arbitrarily long, and for technical reasons you shouldn't really exceed ~2000 characters.

For this reason, some people suggest using POST even though it's arguably not an ideal choice from a semantical point of view.

So, I'm considering allowing both GET and POST:

For queries that fit in a URL: Use GET for clarity, ease of debugging, and semantically accurate requests.
For queries that exceed maximum length of a URL: Use POST and pass query / filtering as body.

Apart from requiring slightly more code and documentation, I can't really see any drawbacks. OTOH I don't think I've stumbled across this approach when reading API documentation.

My questions:

Is there any prior art of such solution in a public "widely available" API?
Are there any drawbacks I'm missing?