Category Archives: REST

Message bodies with REST GET

So today I ran into an issue testing a RESTful service API. The API allows me to query a resource using GET and to provide a couple of optional parameters. I can provide these as either request parameters on the URI or as a JSON payload in the request body.

Testing with curl works fine and I am able to put my parameters into the JSON message body and get an appropriate response from the service using a call like this:

curl -i \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -X GET -d '{"parameter":"value"}' \

Testing with a couple of REST client tools ( restclient and  REST console) however failed. On further investigation it turns out that these tools are not packaging the JSON payload into the request body, presumably because it uses a GET rather than POST or PUT method.

This made me wonder whether it was actually even legal to supply a message body with a GET request.

The HTTP specification says in section 4.3

A message-body MUST NOT be included in a request if the specification of the request method (section 5.1.1) does not allow sending an entity-body in requests.

Section 5.1.1 redirects us to section 9.x for the various methods. None of them explicitly prohibit the inclusion of a message body. However…

Section 5.2 says

The exact resource identified by an Internet request is determined by examining both the Request-URI and the Host header field.

and Section 9.3 says

The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI.

Which together suggest that when processing a GET request, a server is not required to examine anything other that the Request-URI and Host header field.

In summary, the HTTP spec doesn’t prevent you from sending a message-body with GET but there is sufficient ambiguity that it wouldn’t surprise me if it was not supported by all servers.