Are PUT and POST requests required/expected to have a request body?

Question

I'm writting a RESTful api, and at I'm thinking about the process of a user creating a key. I have the following possibilities:

• GET request to /new/<keyname> - although it's very easy I think I won't use this, because I heard GET is for retrieving and/or listing information;
• POST request to /<keyname> - This seemed to me easy and simple enough, but does not pass any data in the request body. Can I do it this way ? Is this weird ?
• POST request to /keys passing in the request body "keyname=SomeKey" - Is this the correct way ?

I looked at this API from joyent and in all their PUT and POST requests they pass some data in the request body. Is this expected ? Is it really wrong not to require a request body in a PUT and POST request ?

Solution 1

I asked this question on the Http-WG. This was the most precise answer I got http://lists.w3.org/Archives/Public/ietf-http-wg/2010JulSep/0276.html

In summary, POST does not require a body. I would expect the same justification can be applied to PUT.

Solution 2

RFC2616 is the base RFC for HTTP 1.1

In the most general form, an HTTP message is this (note the optional body):

generic-message = start-line
                  *(message-header CRLF)
                  CRLF
                  [ message-body ]
start-line      = Request-Line | Status-Line

Reading further gives this:

9.5 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. ...

and

9.6 PUT

   The PUT method requests that the enclosed entity be stored under the
   supplied Request-URI. ...

   The fundamental difference between the POST and PUT requests is
   reflected in the different meaning of the Request-URI. The URI in a
   POST request identifies the resource that will handle the enclosed
   entity. That resource might be a data-accepting process, a gateway to
   some other protocol, or a separate entity that accepts annotations.
   In contrast, the URI in a PUT request identifies the entity enclosed
   with the request -- the user agent knows what URI is intended and the
   server MUST NOT attempt to apply the request to some other resource.

Both POST and PUT include the phrase entity enclosed in the request.

Based on my reading, I believe that a body is desired (a non-normative description, I know) for both POST and PUT.

In the context of REST, POST is create and PUT is update. I can imagine creating an empty object (perhaps a placeholder for future information), but I don't imagine much use of an empty update.

Solution 3

It is not required. You can send a POST/PUT request without a body and instead use query string parameters. But be careful if your parameters contain characters that are not HTTP valid you will have to encode them.

For example if you need to POST 'hello world' to and end point you would have to make it look like this: http://api.com?param=hello%20world

Comments

[Darrel Miller]

What do you mean by "in the context of REST"? Where does REST redefine the meaning of the HTTP POST method?

[DwB]

A REST POST is a create request. I can imagine situations where I want to create a resource identified by a URL using all default values (perhaps identified by an empty body).

[Darrel Miller]

A POST is not necessarily a create request. "Create a sub-ordinate resource" is only one of the suggested meanings. All the http spec says about POST is that it is unsafe and non-idempotent. The remaining semantics are unspecified.

[Pedro Werneck]

POST does require a body, but that body can be an empty document. The difference is subtle, but it's not the same thing. For instance, you still have a mimetype for the empty document.

[Darrel Miller]

@PedroWerneck Can you provide a reference for that assertion? What I have read is not consistent with that perspective.

[Pedro Werneck]

That's what the answer you posted is saying. A zero-length body is not the same thing as no body. You still have to send some of the metadata associated with an empty document.

[Pedro Werneck]

A POST is the method to use for any operation that isn't standardized by HTTP. Using POST as a synonym to the CREATE in CRUD is a common convention in HTTP APIs, but in a REST API, POST can do anything, as long as that's documented by the target media-type.

[Darrel Miller]

@PedroWerneck Body and representation are not the same thing. A representation is both the headers and the body. A zero length body is the same as no body, it is just not the same as no representation. An HTTP request always returns a representation, even if it just the status line.

[Pedro Werneck]

A representation includes the metadata. Saying it's both the headers and body is coupling it to HTTP. ics.uci.edu/~fielding/pubs/dissertation/…

[Darrel Miller]

@PedroWerneck ...but we are talking about HTTP, aren't we? In your understanding, how do I change a HTTP representation that has no body into one that has an empty body?

[Pedro Werneck]

We are talking about REST. HTTP and REST aren't the same thing, and REST isn't coupled to HTTP. If a client follows an hypermedia link to an FTP server, where are the headers? To answer your question, you change it to one that has an empty body, by adding the adequate headers for an empty document with that content-type. Example: a zero-length body is a valid empty text/plain document, but it's not a valid empty application/json.

[Darrel Miller]

@PedroWerneck The OP asked a question about building a REST based API using GET/POST. My assumption was that we were answering the question using HTTP for the uniform interface. If I follow your logic, you are saying that a POST request needs to have a content-type to identify the empty body. Personally, I don't think that is the case, but I don't think it is really worth debating.

[Pedro Werneck]

I'm not saying it requires a content-type to identify the empty body. I'm saying that's the difference between a no-body and an empty body. If you're POSTing to an endpoint which requires JSON, for instance, an empty body would be an error, as an empty json document is 'null', but a no-body would be fine. Got it?

[Darrel Miller]

@PedroWerneck I understand that an empty json document is not the same as no-body and not the same as an empty text/plain document. But that has nothing to do with the original question. I still think a POST is valid with no-body. Which is what you just said in your last comment.