S3 REST API and POST method

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.

Leave a Comment