Hacker News Reader

Comment by polack | Hacker News Reader

POST for update and PUT for create, not the other way around.

EDIT: Wow. A lot of people who think I'm wrong. I agree with you that its not the whole truth, but I think its more true (for most cases) than what the article say.

View on HN

Both POST and PUT can be used to create and update info, the difference is idempotence. In other words, making the same PUT request over and over again won't change the result beyond the initial request.

For example:

- Repeat "POST /entries" 5 times with the same request body and you'll have 5 new and identical entries on the server.

- Repeat "PUT /entries" 5 times with the same request body and you'll overwrite the set of entries on the server 5 times.

- Repeat "POST /entries/1234" 5 times and you'll have 5 times whatever the server says it will do when you POST on a given entry (eg. if the server keeps a modify count on that entry, it will end up incremented by 5)

- Repeat "PUT /entries/1234" 5 times and you'll overwrite that entry 5 times on the server. The end-result will be exactly the same as if you did the request 1 or 100 times, including any counters that are part of the entry itself (because those counters would be part of that PUT request body, see below).

Also, a PUT request is usually made on a specific, unique resource unless you want to overwrite a complete set. If the id specified in the URL doesn't yet exist, it will be created. The request body includes the complete resource data to be created/overwritten. Think file uploads.

A POST request can either create a resource or update parts of an existing resource based on the parameters given in the request body. When it creates, the server assigns the id and creates the URL of the newly created resource. Whether it creates or updates depends on the URL you make the POST request to identifies a specific item or not.

[EDIT: clarified a few things about PUT on an id vs a set)

PUT for creating and complete updating, PATCH for partial updates.

POST has no useful semantics (more correctly, its semantics is just like those of "do"/"execute" verb) and should be used only if no other verb matches. Or for compatibility reasons ("POST /foo\nX-HTTP-Method-Override: PUT")

POST has useful semantics, using PUT requires you know where to put it when the general case is you actually don't, POST for create when you don't know where it goes, the response should then redirect to the created location.

> POST has no useful semantics (more correctly, its semantics is just like those of "do"/"execute" verb) and should be used only if no other verb matches.

While POST is often used as a generic "do"/"execute", its actual defined semantics in RFC2616 are for the server to "accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line."

So, aside from fallback uses, its explicitly the correct verb to use for a request that is intended to create a resource where the client doesn't know the identifier of the resource to be created, only its parent. This is particularly likely to be the case anytime the resource to be created is of a kind that will have a server-assigned key that will be part of the URI.

stuffihavemade is correct. Also, generally a POST request is made to some kind of "resource creating" URI, which includes the URI for the newly-created resource in it's response. A PUT request is typically made to the URI of an existing resource.

This is what I've done in APIs I designed. You end up with requests like this:

  POST /widgets
  Content-Type: application/json
  --
  {"name": "An example widget", "color": "blue"}

With the response being:

  201 CREATED
  Location: /widgets/37
  --
  (no body)

yes, I know I have read somewhere that this is "recommended" for REST apis, but I'll be damned if I can find the source.

This is the pattern that's recommended in Thomas Erl's SOA with REST book. (http://www.amazon.com/dp/0137012519)

No, POST for create and PUT for update is correct. PUT is supposed to be idempotent.

Well, if you know the full object to save I would use PUT. If you expect the server to fill in ID or something similar I would use POST. But why use PUT for update? Dont you have to post the entire object (all fields) with a PUT? So if you just want to update one field a POST is more appropriate?

You could use PATCH instead (which Rails will be using in 4.0).

No, PUT can be for creating too, if the client already knows the final URL. From the spec:

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 a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response.

Reply on news.ycombinator.com