Musicians will understand this analogy. Have you ever tried to learn a piece that goes the wrong way? That is, you’re playing along and it’s so obvious where the next notes are going to go and instead the piece goes off in a completely different direction. Half the time you find yourself playing the notes you think the piece should use rather than the notes it does use.
For me, understanding the difference between HTTP POST and PUT is very much like that. I’ve had a great deal of trouble understanding explicitly RESTful protocols like APP because they follow the actual definition of POST and PUT instead of what is to me clearly the right definition. However, I think I’m finally starting to get it.
My mistake is in thinking that anything that creates a new page is a PUT and anything that changes an existing page is a POST. In SQL terms, POST is an UPDATE and PUT is an INSERT. However, that’s not the case. In fact, the mistake is in trying to model PUT and POST in terms of INSERT and UPDATE. They really aren’t even close.
What actually happens is this. PUT puts a page at a specific URL. If there’s already a page there, it’s replaced in toto. If there’s no page there, a new one is created. This means it’s like a DELETE followed by an insert of a new record with the same primary key.
POST, however, really has no equivalent in SQL. POST sends some data to a specified URL. The server on the other end of this URL can do whatever it wants with this data. It can store it somewhere private. (HTTP 204 NO CONTENT). It can store it in the page at the URL that was POSTed to (HTTP 205 RESET CONTENT). It can store it in a new page, in which case it returns the URL of that page in the Location field of the HTTP response header (HTTP 201 CREATED). It can use it as input for several different existing and new pages. It can throw the information away. It can insert, update, or delete records in a database (or all of the above). It can start brewing coffee (HTTP 202 ACCEPTED). It can start global thermonuclear war. POST is decidely non-side-effect free and non-idempotent.
PUT is a much more limited operation that never does anything more than PUT one page at a specified URL. It is idempotent, which is a fancy way of saying that doing it twice is the same as doing it once. Both PUT and POST can be used to create new pages. However PUT should be used when the client specifies the location for the page. PUT is normally the right protocol for a web editor like DreamWeaver or BBEdit. POST is used when the client gives sends the page to the the server, and the server then tells the client where it put it. POST is normally the right protocol for a blog editor like TypePad or anything that inputs into a content management system. In SQL analogy, POST is an INSERT with an automatically generated primary key, and PUT is an INSERT that specifies the primary key in the INSERT statement.
