5 ms·

Quick summary: PUT is idempotent, and should be used when you're sending the full text or properties of an item, or otherwise doing some where doing it a secon

Quick summary: PUT is idempotent, and should be used when you're sending the full text or properties of an item, or otherwise doing some where doing it a second time is harmless. POST is not, and should be used for requests like "increment this field" or "add a new sub-item to this parent item" where doing it twice will give a very different result than doing it once.

keefe 16y ago
couchdb then technically violates this due to revision numbers
- epochwolf 16y ago
  I'd say the mapping is good enough. PUT updates a current object, which can be done again. POST creates a new object which can't be repeated without producing another article. CouchDB has automatic versioning which is mostly transparent to most operations. (on a single instance)
  - keefe 16y ago
    It was a nitpicky comment, I guess cause I am contemplating the meaning of idempotent. Two identical PUTs on an existing doc will not change the database so I guess that's OK, but their response will be different insofar as the 2nd will fail.
    - epochwolf 16y ago
      I don't think the failed response matters. You can replay a PUT request without altering the state on the server. (Aside from the single object you're manipulating.) Replaying a POST gets you two objects with the same data.
      - keefe 16y ago
        I think you're right because the 2nd PUT doesn't change the value of variables on the server.
calcnerd256 16y ago
No. http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 versus http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5 http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5 makes it clear that you PUT something somewhere and that you POST something to the resource located somewhere. That is the difference. The idempotence follows from that, but it is not the important semantic part.
- mjw 16y ago
  Personally I feel that idempotence should be the only important semantic component of PUT. Although the spec makes stronger assertions about its semantics than this, namely that the body of a PUT is supposed to a full replacement for the resource at the URL in question. However I don't think any clients or middleware take advantage of this or would reliably be able to take any useful advantage of this. Whereas idempotence is something which client and middleware can usefully take advantage of - eg a browser can safely re-try an idempotent request whereas it can't safely retry a general POST. Allowing PUT to be used for requests which are idempotent but not technically full replacement updates (eg partial updates) would allow middleware to know that they're safe to repeat.
  - mjw 16y ago
    To summarise my point there: By constraining the use of PUT to 'full replacement' updates, you deny people a useful way to signal idempotence for other more general kinds of idempotent updates.
    - briansmith 16y ago
      That is what PATCH is for.
      - mjw 16y ago
        Again the (in this case draft) RFC begs to differ: http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-11.html http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-... "PATCH is neither safe or idempotent as defined by [RFC2616] Section 9.1." The only semantics it has seems to be "change this resource in some way". Sometimes such a change might be idempotent, sometimes not, and the PATCH method provides no way of communicating this. Personally I see little advantage from adding a PATCH method. Its semantics, as far as any generalised client software or middleware are concerned, seems the safe as POST. Really the question which this raises is: for what reasons are new REST methods justified? I think Fielding et al are vague on this topic, and I think the vagueness shows in HTTP (and in proposed extensions like PATCH) Personally I think new methods should only be justified where they have generalised semantics which can be exploited by middleware (or middleware-like layers in client software) and where no existing method is available to express these semantics. Terms like 'safe' and 'idempotent' are relevant and useful properties to consider at this level. The data-level semantics (like 'applies a diff to' or 'does something approximately like a full update to') aren't really relevant when it comes to request methods, unless they are properties which it's genuinely useful for generic middleware to know about. I say this because hypertext and standardised hypertext media types and relations are already great at helping people discover available operations, together with their data/domain-level semantics, without the need for any new request methods.
davidmathers 16y ago
Weird that calcnerd256 is being down-voted for linking to w3.org while mjw is being up-voted for expressing personal feelings. Here's the relevant paragraph from the w3.org link: 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.

keefe 16y ago

couchdb then technically violates this due to revision numbers

epochwolf 16y ago
I'd say the mapping is good enough. PUT updates a current object, which can be done again. POST creates a new object which can't be repeated without producing another article. CouchDB has automatic versioning which is mostly transparent to most operations. (on a single instance)
- keefe 16y ago
  It was a nitpicky comment, I guess cause I am contemplating the meaning of idempotent. Two identical PUTs on an existing doc will not change the database so I guess that's OK, but their response will be different insofar as the 2nd will fail.
  - epochwolf 16y ago
    I don't think the failed response matters. You can replay a PUT request without altering the state on the server. (Aside from the single object you're manipulating.) Replaying a POST gets you two objects with the same data.
    - keefe 16y ago
      I think you're right because the 2nd PUT doesn't change the value of variables on the server.

calcnerd256 16y ago

No. http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 versus http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5 http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5 makes it clear that you PUT something somewhere and that you POST something to the resource located somewhere. That is the difference. The idempotence follows from that, but it is not the important semantic part.

mjw 16y ago
Personally I feel that idempotence should be the only important semantic component of PUT. Although the spec makes stronger assertions about its semantics than this, namely that the body of a PUT is supposed to a full replacement for the resource at the URL in question. However I don't think any clients or middleware take advantage of this or would reliably be able to take any useful advantage of this. Whereas idempotence is something which client and middleware can usefully take advantage of - eg a browser can safely re-try an idempotent request whereas it can't safely retry a general POST. Allowing PUT to be used for requests which are idempotent but not technically full replacement updates (eg partial updates) would allow middleware to know that they're safe to repeat.
- mjw 16y ago
  To summarise my point there: By constraining the use of PUT to 'full replacement' updates, you deny people a useful way to signal idempotence for other more general kinds of idempotent updates.
  - briansmith 16y ago
    That is what PATCH is for.
    - mjw 16y ago
      Again the (in this case draft) RFC begs to differ: http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-11.html http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-... "PATCH is neither safe or idempotent as defined by [RFC2616] Section 9.1." The only semantics it has seems to be "change this resource in some way". Sometimes such a change might be idempotent, sometimes not, and the PATCH method provides no way of communicating this. Personally I see little advantage from adding a PATCH method. Its semantics, as far as any generalised client software or middleware are concerned, seems the safe as POST. Really the question which this raises is: for what reasons are new REST methods justified? I think Fielding et al are vague on this topic, and I think the vagueness shows in HTTP (and in proposed extensions like PATCH) Personally I think new methods should only be justified where they have generalised semantics which can be exploited by middleware (or middleware-like layers in client software) and where no existing method is available to express these semantics. Terms like 'safe' and 'idempotent' are relevant and useful properties to consider at this level. The data-level semantics (like 'applies a diff to' or 'does something approximately like a full update to') aren't really relevant when it comes to request methods, unless they are properties which it's genuinely useful for generic middleware to know about. I say this because hypertext and standardised hypertext media types and relations are already great at helping people discover available operations, together with their data/domain-level semantics, without the need for any new request methods.

davidmathers 16y ago

Weird that calcnerd256 is being down-voted for linking to w3.org while mjw is being up-voted for expressing personal feelings. Here's the relevant paragraph from the w3.org link: 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.