Designing a REST API endpoint that accepts a lot of data as input

Question

Let's assume we're designing REST API. We have some entity, let's call it foo

So the endpoint that returns a list of foo entities filtered according some predicates would look like:

GET /foos?filtering-parameters-here

The issue though is that the size of the filtering-parameters payload is potentially HUGE. In some cases it may easily be more than 6-7kb.

Some clients (browsers) are trimming the URL in case if it is of that size.

The "obvious" solution is to change it to POST and send parameters in the body. But it will make the endpoint not semantically clean.

So what would be the correct RESTful way?

Answer 1

I've heard the recommendation of using POST in such circumstances, but not to merely accept parameters.

Instead, a POST request is fired with the complex filtering data as the message body, and this predictably creates a resource; let's call it a search:

POST /search HTTP/1.1

The response identifies via Location the result set:

Location: http://example.com/search/798342

A subsequent GET request can be made against the location, returning the result set. This works particularly well when the result set may take some time to generate (which could be the case given complex filtering rules) and maintains alignment with the expectations of HTTP.

GET /search/798342 HTTP/1.1

If the search results are not ready, yield a 404.

Searches, like anything else, can/should be represented as resources. An added benefit is caching. If you cache the results of a complex operation, the cache lifetime can be communicated from the search result set resource.