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 ?

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

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

Answer 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

Answer 4

Probably the best way is your third option: POST to /keys with keyname=SomeKey.

Here's why: You may wish to add another function to your API, for example create_new_user. It would then be difficult to tell the difference between a user trying to POST a key called create_new_user and a user trying to use the create_new_user function.

You are correct in saying that you should not be using GET to do this operation as the GET operation "SHOULD NOT have the significance of taking an action other than retrieval." (RFC 2616).

Answer 5

To answer your question in one line. Yes it is expected to have Body/Content in body, but it is not required(Mandatory).

Answer 6

According to okHttp3 (an HTTP library for android): the following methods need a body: POST, PUT, PATCH, PROPPATCH (WebDAV) and REPORT (source). It even crashes if you try to do a request with the given methods without a body.