21

I know HTTP PUT is an idempotent request that store something at a specific URI, according to the definition (quoted from the rfc)

The PUT method requests that the enclosed entity be stored under the supplied Request-URI.

But what is the definition of 'enclosed entity'? It doesn't seem possible for me to send form data (like for HTTP POST request) over. What about sending representation of the entity via JSON/XML or in other serialization formats?

In short, how does one send a HTTP PUT request over to store/update info at a specific URI then?

Jeffrey04
  • 6,138
  • 12
  • 45
  • 68

5 Answers5

15

In REST you have:

GET - retrieve resource
POST - create new resource
PUT - update existing resource
DELETE - delete resource

So the PUT verb is used to update an existing resource on the server. Depending on the client there are various ways of sending a PUT request. For example with jquery AJAX:

$.ajax({
    type: 'PUT',
    url: '/products/123',
    data: { name: 'new product name' }
});
Darin Dimitrov
  • 1,023,142
  • 271
  • 3,287
  • 2,928
  • but how do you issue a HTTP PUT request? is the one posted in the following question the right way? http://stackoverflow.com/questions/2719610/should-i-allow-sending-complete-structures-when-using-put-for-updates-in-a-rest-a – Jeffrey04 Dec 18 '10 at 09:24
  • 1
    @Jeffrey04, it depends on what the server expects. In the example you are showing it is XML. But you could use other formats as well. I would recommend you watching [this video on using REST for SOA](http://www.infoq.com/presentations/Using-REST-for-SOA). – Darin Dimitrov Dec 18 '10 at 09:26
  • http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/ good explaination of the different uses of POST and PUT. ITs usage dependant, not action. – David J Eddy Jun 27 '14 at 15:34
  • Sidenote: having a clear-cut URL like ```/products/123``` for the PUT also makes it easier to do the cache-invalidation for this particular entity. – Siddhartha Jun 01 '20 at 19:56
12

The enclosed entity is the payload data contained in the HTTP message body (after any transfer encodings have been removed.) If you're having trouble sending the message body then it could be that you've forgotten to include a Content-Length header - that's one of two ways to indicate that the HTTP message has a body.

PUT is the same as POST except for this semantic difference: With POST the URI identifies a resource that will handle the entity, such as a servlet. With PUT the URI identifies the entity itself, for example a file that will be created/replaced with the contents of the entity body.

Ciaran Keating
  • 2,793
  • 21
  • 19
6

So a HTTP PUT request is often issued to replace the currently stored resource at a given URI. For example, there's a book stored at https://example.org/book/1 where the data can be representated in JSON as follows,

$ curl --request GET https://example.org/book/1
{
    "title": "Stackoverflow Compilation Book 1",
    "year": 2019
}

Suppose someone wants to fix the year field because the fictional book was published last year (2018), he/she would have to send the COMPLETE updated book info over through a HTTP PUT request.

$ curl --request PUT
      --header "Content-Type: application/json"
      --data '{"title": "Stackoverflow Compilation Book 1", "year": 2018}'

Notice the change in year attribute.

Considering a HTTP PUT request is essentially a replace operation, one can also replace the book represented by the URI to something else. For instance,

$ curl --request PUT
      --header "Content-Type: application/json"
      --data '{"title": "Some random book that nobody publishes", "year": 2019}'

The attached data can be in any format (usually also specified in the request header Content-Type, as shown above), as long as it is supported, usually reported by Accept response header (which denotes what kind of data type the application is willing to deal with). Further validation would be handled by the application code to determine whether the submitted data is valid.

Jeffrey04
  • 6,138
  • 12
  • 45
  • 68
2

You send a HTTP PUT where the body is the 'enclosed entity' that you wish to store under the requested URL. Very similar to POST, it is only the semantics as specified in the RFC, that differ.

driis
  • 161,458
  • 45
  • 265
  • 341
  • Perhaps you're confused about this: you're actually sending an HTTP POST request — your web browser doesn't support PUT. You pass type=PUT in the form data so your web app (i.e. Rails) knows what to do. – Paul Schreiber Dec 18 '10 at 16:11
  • @Paul I'm actually developing a restful api site via php (zend_framework), but I didn't know how PUT is actually done (hence the question) and doesn't look like form input should/can be used. My webserver and the php script are capable of processing PUT requests tho. – Jeffrey04 Dec 18 '10 at 18:39
1

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.

prasad
  • 11
  • 1