Newsletter sign-up
View all newsletters

Enterprise Java Newsletter
Stay up to date on the latest tutorials and Java community news posted on JavaWorld

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

REST for Java developers, Part 1: It's about the information, stupid

A resource-oriented approach to Web services

  • Print
  • Feedback

Page 3 of 4

GET

GET, the most familiar verb, is how your clients ask for the content that they seek. A user either knows a name and types it in directly or receives a link somehow and clicks through. Issuing a GET verb transfers the state of a resource in some representation from a server to a client. The GET verb is called an idempotent request, meaning that there are no consequences to issuing it; nothing changes on the server.

When you mix the stateless request style with URLs to identify the resources and the idempotency of the GET request, you achieve a compound key:

http://someserver/ + /service + /1234?foo=bar&bat=baz

This joint key represents something like a hash key into a computational result set. You can imagine caching all manner of queries and results. Being able to identify these results means you can build infrastructure that does not need to burden the back-end servers. I'll revisit these ideas in a future article in this series.

POST and PUT

It is slightly awkward to talk about POST without also talking about PUT. They seem to do the same thing -- create or update a resource -- but they come from different traditions. POST is from the Usenet community. When people wanted to create a new information resource, say a message about the previous night's "Star Trek" episode, they would create it locally and then POST it to a proxy for the community. No central authority was responsible, so there was no one place to handle the state of the resource. For the same reason, we use POST to create things like orders on e-commerce sites. Until the user transfers an order's state from a browser to the server, the server has no notion of the order's existence or identity. It therefore has no name. As such, we do not know what to call the resource. This is why we have historically POSTed forms to a servlet that processes the request for us. If we have permission to create or update the resource, we will get a response indicating success and perhaps a new address with which to address the resource.

RESTful security

Not all resources can or should support all verbs. Consider what makes sense and who has a business need to manipulate or view the resource. You can control the scope under which your RESTful service responds to verbs based on a request's context. Because your URLs map to named information resources, not arbitrary services, applying a declarative security policy for specific content is straightforward. The details of building this kind of a system are highly implementation-specific, but they easily map into Spring Security, LDAP, single sign-on, and other authentication and authorization systems.

PUT comes to us as part of Tim Berners-Lee's vision of the Web. It is intended as a way to overwrite a named resource. If you create a document that has a specific URL and you want to update it, you can PUT a new version to the URL update the resource.

In general, if you know the name of the resource and wish to overwrite the state, you should probably use a PUT. Otherwise, a POST is a good alternative, particularly if you only want to update a portion of the resource (such as an address or phone number).

DELETE

Thankfully, the public Web doesn't include much support for the DELETE action. Otherwise, factions that differ on various topics might be removing each other's content. On information spaces that you control, however, issuing a DELETE request to a named resource is an important part of the resource's life cycle.

  • Print
  • Feedback

Resources

More