parameter longer than the length limit of GET into a RESTful interface

Question

In a Restful API, it is better to use GET to list a collection. However, in our scenario, we allow people query with a list of parameters (say CodeList) and then return details.

As we allow upto 500 codes in the codelist parameter, it is possible that the size limit of 2,048 characters for a GET url is not enough. What is good way to handle this? I can think of two options:

1. Just use POST to return a list of collection.
2. Still use GET, but put the parameter in request body other than request url.

From a API design point of view, which option is bit better? Or maybe there are better options I am not aware of?

Answer 1

use GET, but put the parameter in request body other than request url.

Out of bounds

A payload within a GET request message has no defined semantics -- RFC 7231.

The problem is that general purpose components are not going to understand that the payload of your GET request is part of the identifier for the resource, which means that all kinds of weird things can happen.

The HTTP-WG adopted a proposal to standardize a safe http method where the body is semantically significant. But it isn't yet registered as a standard.

In the mean time, it is okay to use POST.

Answer 2

My suggestion is:

1. Allow the caller to POST a query. This is a creational act.

2. The server creates the query results and associates it with a unique identifier.

3. The API returns an HTTP 303 redirect with the unique identifier

4. The caller sends a GET with the unique identifier to retrieve the results

5. The resultset is returned in response to the GET request

The benefit of this approach is that it allows the client to cache the resultset, which can improve responsiveness and reduce load on your server.