6

REST recommends that queries (not resource creation) be done through the GET method. In some cases, the query data is too large or structured in a way that makes it difficult to put in a URL, and to address this, a RESTful API is modified to support queries with bodies.

It seems that the convention for RESTful queries that require bodies is to use POST. Here are a few examples:

Queries don't modify the internal state of the system, but POST doesn't support idempotent operations. However, PUT is idempotent. Why don't RESTful APIs use PUT with a body instead of POST for queries that require a body?

NOTE: A popular question asks which (PUT vs POST) is preferred for creating a resource. This question asks why PUT is not used for queries that require bodies.

Community
  • 1
  • 1
lreeder
  • 12,047
  • 2
  • 56
  • 65
  • I'm confused about the question. Are you asking about GET vs PUT or PUT vs POST? The first sentence says the former, but the last paragraph suggests the latter. – Phlucious Oct 19 '15 at 17:21
  • 3
    The question asks about PUT vs POST for **queries** with body. You can't do a GET with body (or at least it's not widely supported), so that leaves the choices as PUT or POST among main/common HTTP verbs, ignoring REPORT and other verbs. – lreeder Oct 19 '15 at 17:24

2 Answers2

4

No. PUT might be idempotent, but it also has a specific meaning. The body of the request in PUT should be used to replace the resource in the URI.

With POST no such assumptions are being made. And note that using a POST request means that the request might not be idempotent, in specific cases it still might be.

However, you could do it with PUT, but it requires you to jump through an extra hoop. Basically, you could create a "query resource" with PUT, and then use GET immediately after to fetch the results of this query resource. Perhaps this was what you were after, but this is the most RESTful, because the resulting query results can still be linked to. (something which is completely missing if you use POST requests).

Evert
  • 93,428
  • 18
  • 118
  • 189
-2

You should read the standard: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

The definition of POST:

The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.

The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either 200 (OK) or 204 (No Content) is the appropriate response status, depending on whether or not the response includes an entity that describes the result.

The definition of PUT

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

If the resource could not be created or modified with the Request-URI, an appropriate error response SHOULD be given that reflects the nature of the problem.

Another thing that PUT is not cacheable while POST is.

Responses to this method are not cacheable, unless the response includes appropriate Cache-Control or Expires header fields.

e.g. http://www.ebaytechblog.com/2012/08/20/caching-http-post-requests-and-responses/

inf3rno
  • 24,976
  • 11
  • 115
  • 197
  • "Another thing that PUT is not cacheable while POST is." — POST is cacheable? – Kijewski Oct 19 '15 at 18:08
  • @Kay You should read the standard too. `Responses to this method are not cacheable, unless the response includes appropriate Cache-Control or Expires header fields. ` – inf3rno Oct 19 '15 at 18:13
  • 2
    Generally, RTFM answers are not useful, particularly when the question clearly shows research effort. – jaco0646 Oct 19 '15 at 18:24
  • @jaco0646 REST is about the Fielding dissertation and applying standards like HTTP, URI, MIME types, etc... If somebody does not read these and/or cannot apply these then I can hardly call that a research effort. – inf3rno Oct 19 '15 at 19:08