S3 REST API and POST method

I'm using AWS S3 REST API, and after solving some annoying problems with signing it seems to work. However, when I use correct REST verb for creating resource, namely POST, I get 405 method not allowed. Same request works fine with method PUT and creates resource.

Am I doing something wrong, or is AWS S3 REST API not fully REST-compliant?

Yes, you are wrong in mapping CRUD to HTTP methods.

Despite the popular usage and widespread misconception, including high-rated answers here on Stack Overflow, POST is not the "correct method for creating resource". The semantics of other methods are determined by the HTTP protocol, but the semantics of POST are determined by the target media type itself. POST is the method used for any operation that isn't standardized by HTTP, so it can be used for creation, but also can be used for updates, or anything else that isn't already done by some other method. For instance, it's wrong to use POST for retrieval, since you have GET standardized for that, but it's fine to use POST for creating a resource when the client can't use PUT for some reason.

In the same way, PUT is not the "correct method for updating resource". PUT is the method used to replace a resource completely, ignoring its current state. You can use PUT for creation if you have the whole representation the server expects, and you can use PUT for update if you provide a full representation, including the parts that you won't change, but it's not correct to use PUT for partial updates, because you're asking for the server to consider the current state of the resource. PATCH is the method to do that.

In informal language, what each method says to the server is:

• POST: take this data and apply it to the resource identified by the given URI, following the rules you documented for the resource media type.

• PUT: replace whatever is identified by the given URI with this data, ignoring whatever is in there already, if anything.

• PATCH: if the resource identified by the given URI still has the same state it had the last time I looked, apply this diff to it.

Notice that create or update isn't mentioned and isn't part of the semantics of those methods. You can create with POST and PUT, but not PATCH, since it depends on a current state. You can update with any of them, but with PATCH you have an update conditional to the state you want to update from, with PUT you update by replacing the whole entity, so it's an idempotent operation, and with POST you ask the server to do it according to predefined rules.

By the way, I don't know if it makes sense to say that an API is or isn't REST-compliant, since REST is an architectural style, not a spec or a standard, but even considering that, very few APIs who claim to be REST are really RESTful, in most cases because they are not hypertext driven. AWS S3 is definitely not RESTful, although where it bears on your question, their usage of HTTP methods follows the HTTP standard most of the time.

+--------------------------------------+---------------------+
|                 POST                 |         PUT         |
+--------------------------------------+---------------------+
| Neither safe nor idempotent Ex: x++; | Idempotent Ex: x=1; |
+--------------------------------------+---------------------+

To add to @Nicholos

From the http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

POST:

> The posted entity is subordinate to the URI in the same way that a > file is subordinate to a directory containing it, a news article is > subordinate to a newsgroup to which it is posted, or a record is > subordinate to a database > > 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 > > If a resource has been created on the origin server, the response > SHOULD be 201 (Created)

PUT:

> The PUT method requests that the enclosed entity be stored under the > supplied Request-URI. If the Request-URI refers to an already existing > resource, the enclosed entity SHOULD be considered as a modified > version of the one residing on the origin server. 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. If an existing resource is modified, either the > 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate > successful completion of the request

IMO PUT can be used to create or modify/replace the enclosed entity.

In the original HTTP specification, the resource given in the payload of a POST request is "considered to be subordinate to the specified object" (i.e. the request URL). TimBL has said previously (can't find the reference) that it was modelled on the identically-named method in NNTP.