Actually its nothing to do with REST for PUT and POST. In general how HTTP PUT works and how POST work, is what I want to demonstrate through code.
Why REST is considered, usually we get confused while developing REST API, that when to use PUT and when to use POST for update and insert resource.
Lets start with the actual definition of these methods (copied form http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)
POST
The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.
The actual function performed by the POST method is determined by the server and is usually dependent on the Request-URI. The posted entity is subordinate to that 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) 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).
Responses to this method are not cacheable, unless the response includes appropriate Cache-Control or Expires header fields. However, the 303 (See Other) response can be used to direct the user agent to retrieve a cacheable resource.
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. If the resource could not be created or modified with the Request-URI, an appropriate error response SHOULD be given that reflects the nature of the problem. The recipient of the entity MUST NOT ignore any Content-* (e.g. Content-Range) headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in such cases.
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.
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. If the server desires that the request be applied to a different URI.
Lets Go back to our REST example
Ok, now to make it more clear in REST terms, lets consider a example of Customer and Order scenario, so we have API to create/modify/get customer but for order we do have create order for customer and when we call GETÂ /CustomerOrders API will get the customer orders.
APIs we have
GET /Customer/{custID}
PUTÂ /Customer/{custID}
POSTÂ /Customer custID will be part of the HTTP body (to demonstrate difference between POST and PUT, otherwise for stated requirement it wont required)
POST /Order/{custID}
GET /CustomerOrders/{custID}
I have enable browser cache by adding header “Cache-Control”. so lets first see flow of PUT and GET for customer
Initial load, I called PUT /Customer/1 which placed new resource on server and then called GET /Customer/1 which returned me the customer I placed. now when I again call the GET /Customer/1 I will get the browser “Cached” instance of customer.
Now you call PUT /Customer/1 with updated values of customer, and then call GET /Customer/1, you will observer that browser makes calls to server to get new changed values. and if you add debug point or increase the wait time in you PUT, and make parallel request for GET (Ajax), then GET request will be pending till PUT is served, so browser makes cached instance of resource to stale.
In case of POST, new resource will be posted to server, but if POST request is not served, and you request for same resource using GET, cached instance will be returned. Once the post is successful and you make GET call to the resource, browser will hit to server to get new resource.
I added delay of 100 milliseconds in both PUT and POST and made request as
1) Called GET /Customer/1 multiple times to check if I am getting cached resource. Then I called PUT, and immediately called GET, and GET was pending till PUT is served. below if the screen shot which explains it.
2) Called GET /Customer/1 multiple times to check if I am getting cached resource. Then I called POST, and immediately called GET, and GET was served from cache. below if the screen shot which explains it.
So example explains all, so in our customer order case, customer should be PUT for new customer and for updating customer as we are retrieving the customer using same resource URI but for Order we used POST as we don’t have same URI for GET orders.
One More Example for PUT
You have a site which hosts different articles and documents. Client has sent request to create new documents which has title âWhyToUsePutForCreationâ then your request will look like PUT /article/WhyToUsePutForCreation and once the application creates it, application will respond with 201. i.e. resource created. Now from client I can list the new document in documents list and which will be fetched by calling GET /article/WhyToUsePutForCreation
Download Code
Strange Browser Behavior : If I increase the delay in PUT method to 1000 milliseconds. First I made request to PUT /Customer/1, and immediately sent request for GET, browser wait for PUT to get complete and after that GET request returns either cached resource or calls the server to get new resource.
I tried with different delay time, and it is not fixed behavior of Browser about, when to return the cached resource (old one) and when to request resource from server.
I am not sure if this is correct behavior, but I think its a problem with browser if I consider description of PUT.
YOGESHINDE 