POST is not always "create" and PUT is not always "update". about api-standards

[benbunk]

I'm not entirely sure, but it seems that the HTTP Verbs chart https://github.com/WhiteHouse/api-standards#http-verbs is trying to avoid the sort of ambiguity that the HTTP protocol introduces (http://tools.ietf.org/html/rfc2616#page-51) in regard to POST, PUT, and method overrides.

For instance the chart says the the PUT method should only update and if the entity doesn't exist it should return an error. In the HTTP spec it is entirely valid for an origin server to only update entities when the PUT method is used as long as the server returns the correct status code

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

(http://tools.ietf.org/html/rfc2616#section-9.6)
The operative word is "can" essentially allowing the server to choose if it wants to implement the create operation or not. While in general it is perfectly acceptable to create an entity with PUT I believe the spirit of this document is to avoid such ambiguity. The same goes for POST and method overrides.

However, there is some ambiguity that isn't clarified here in regards to the responses from the PUT and POST methods.
For instance with POST if server creates an entity that results in a new URI then,

If a resource has been created on the origin server, the response
SHOULD be 201 (Created) and contain an entity which describes the
status of the request and refers to the new resource, and a Location
header (see section 14.30).

(http://tools.ietf.org/html/rfc2616#section-9.5)
The operative word being "should" which is even written in all caps to draw attention to itself in the document. Meaning that it doesn't really need to behave this way. So clarification would be appreciated.

Further if the action doesn't result in an entity with a URI we know it's appropriate but not required to return a 200 or 201 response.

"The action performed by the POST method might not result in a
resource that can be identified by a URI. In this case, either 200
(OK) or 204 (No Content) is the appropriate response status,
depending on whether or not the response includes an entity that
describes the result."

(http://tools.ietf.org/html/rfc2616#section-9.5)
Again, clarification here would be good. It would seem this type of behavoir is really geared more towards the method overloading aspect of the POST method and may not need clarification if there won't be any generic actions being created with the POST method.