Uniform Interface and REST March, 2009
I'm reading Restful Web Services by Richardson & Ruby and I'm covering the use of HTTP verbs to specify operations on a resource. One thing this chapter has drilled into my brain is the importance of breaking things down into resources and identifying a resource with a good, descriptive URI. Using HTTP verbs to express what you want to do with that resource is pretty straight forward although the PUT/POST definitions were new to me:
- GET - Exactly that, get the resource.
- DELETE - Exactly that, delete the resource.
- OPTIONS - Returns the HTTP verbs that can be used with this resource (IE: The operations that can be performed).
- HEAD - Get metadata about the resource but not the resource itself. The description given in the book is "gives you exactly what a GET request would give you, but without the entity body." Now I understand that, lets say that the resource is a large zip file and you don't want the file just info about the file. But does that mean you actually serve just the headers without the body? Or could you serve and xml body that has metadata about the file other than what would be in the response headers; description, tags, creator? Not completely clear on that one.
- PUT - One intent is to simply modify the resource. PUT is also used to create the resource but only if you are determining the URI and you are not appending a child resource to a parent resource. So the example in the book is a bucket in Amazon S3. You can use PUT to create a new bucket here for example: http://s3.amazonaws/MyNewBucket. You are specifying the URI and your not appending a child resource to a parent resource.
- POST - POST is used to append a child resource to its parent when its parent is in charge of determining its URI. The example in the book is a blog. You might POST a blog entry on the resource http://blog.yada.com/MyBlog and the resulting blog post could be created as http://blog.yada.coom/MyBlog/10/5/2008/0. The post is appended to the blog and you don't have a say in the appended items URL. The client is notified of the URI of the newly created resource in the "Location" header in the response and a 201 HTTP response code. Now what would happen if you instead did a PUT to http://blog.yada.com/MyBlog? It should be updating the blog, as in the blog title, description, etc.
These verbs form a uniform interface for working with resources on the web.