REST request cannot be encoded for GET (URL too long)

Question

Example:

• URL: http://example.com/collection/a%20search%20term

• Method: GET

• Response: All items in collection matching a search term.

Problem: The search term may be so long that it breaks the web server's maximum URL length.

How do I allow extremely long search terms and still stay RESTful?

Marcionism

Answer 1

For inspiration, I just looked at Google Translate's API v2, which is "using the RESTful calling style."

Naturally, texts to be translated can be quite long. And so Google optionally allows sending a request with POST, but with a twist:

To use POST, you must use the X-HTTP-Method-Override header to tell the Translate API to treat the request as a GET (use X-HTTP-Method-Override: GET).

So it is possible to semantically transform a POST request into a GET request.

(This discovery led me to add the x-http-method-override tag to my question.)

Marcionism

Hey feklee. I checked the link you posted, but I can't find it's using the X-HTTP-Method-Override. In v2, seems like Google avoid using this header. I actually think using the header is hacky. This header's main use case is for old browsers which doesn't support DELETE/PUT and so on. If you already need a POST to handle a big input content, why do you need this header? – Herl

Answer 2

REST does not restrict POST to creation. Be careful with mapping CRUD to HTTP methods and assume that's RESTful. POST is the method used for any action that isn't standardized by HTTP.

Since the standard doesn't establish a limit for URIs, this can be considered a broken implementation, and it's ok to fix it. As long as the workaround is loosely coupled to your API, you are still RESTful. This means your API shouldn't implement a translation or override directly, but on a pre-processor of some kind that rewrites the request properly. It should be clearly documented somewhere that this is due to a broken implementation, and you expect it to eventually become obsolete.

Canula

Thanks for your thoughts, especially concerning REST vs. CRUD. Specifying X-HTTP-Method-Override: GET like Google does it looks like a good way to define the exception (workaround) and document it. – Marcionism

That's fine, as long as that behavior is not implemented by the resource implementation itself. – Canula

Answer 3

It's a bad smell if your query can be so long that it exceeds the maximum length (de facto for browsers is 2000 characters but it can be higher for other means of accessing REST APIs).

If the user can pass in that much data, it should go in the request body/data field, not in the URL.

Phira

That would mean using POST, and according to REST principles POST is used for creating entries in collections. Or am I missing something? – Marcionism

you could in theory add a body to a GET request, but not all clients support it. You have to ask yourself, which is more confusing, adding a body to a GET or telling the user to POST for something that should be a GET? You could allow the user to specify the data in either the URL or the body, and tell them to use the body if the URL is too long. Or you could increase the allowed # characters on the web server backend, or change the data format so that this rarely happens... – Phira

Another question: Why do you write "If the user can pass in that much data, it should go in the request body/data field, not in the URL."? Asides from size limits, what is the disadvantage of passing lengthy data via URL? You may consider adding this information to your answer. – Marcionism

it's specifically because of the size limitations. – Phira

Unlike what @Phira says, you cannot really pass a request body on a GET request because it is likely to be stripped out by something along the way and not reach your server – Geotectonic