34

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 ?

João Pinto Jerónimo
  • 9,586
  • 15
  • 62
  • 86

6 Answers6

29

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.

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 11
    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. – Pedro Werneck Apr 16 '15 at 19:59
  • 2
    @PedroWerneck Can you provide a reference for that assertion? What I have read is not consistent with that perspective. – Darrel Miller Apr 17 '15 at 14:42
  • 1
    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 Apr 17 '15 at 15:25
  • 1
    @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. – Darrel Miller Sep 02 '15 at 01:54
  • A representation includes the metadata. Saying it's both the headers and body is coupling it to HTTP. http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_2 – Pedro Werneck Sep 04 '15 at 00:29
  • 2
    @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? – Darrel Miller Sep 04 '15 at 00:43
  • 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. – Pedro Werneck Sep 04 '15 at 04:04
  • 1
    @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. – Darrel Miller Sep 04 '15 at 13:13
  • 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? – Pedro Werneck Sep 04 '15 at 14:15
  • 5
    @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. – Darrel Miller Sep 04 '15 at 15:03
7

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.

DwB
  • 37,124
  • 11
  • 56
  • 82
  • 8
    What do you mean by "in the context of REST"? Where does REST redefine the meaning of the HTTP POST method? – Darrel Miller Sep 06 '11 at 21:58
  • 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). – DwB Sep 07 '11 at 04:02
  • 7
    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. – Darrel Miller Sep 07 '11 at 12:20
  • 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. – Pedro Werneck Apr 17 '15 at 15:27
1

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

marko982
  • 156
  • 6
-1

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

Vreddhi Bhat
  • 113
  • 7
-1

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.

Cristan
  • 12,083
  • 7
  • 65
  • 69
-1

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

Community
  • 1
  • 1
Jack Edmonds
  • 31,931
  • 18
  • 65
  • 77