Packetizer Logo
 

Representational State Transfer (REST)

Representational State Transfer (REST) is a design approach, not a new technology. Even so, people speak of implementing REST and REST interfaces as if it is a new technology, so we will not try to persuade the world that REST is more theory than practice. In practice, REST is implemented with HTTP and XML or JSON.

REST enables two computers to talk to each other, not unlike technologies like RPC, CORBA, SOAP, and DCOM. OK, to be fair, it is different. Well, at least in theory. If one deviates from the theory, then one is usually quickly accursed of not writing RESTful Web Services. Dare we say that such deviations are unRESTful?

Resources and Representations

In the world of REST, there are two key terms that you need to learn: resources and representations. These are actually both very simple concepts, but admittedly confusing the first time one encounters the words. But, we are fairly certain that these words were created because it sounds much better than referring to a "thing" you want to talk to and the "stuff" you want to send. We believe you might agree.

A resource is some "thing" located at some address to which a computer would like to transmit information or from which it would like to receive information. An example of a "thing" might be this web page. Your web browser might want to retrieve it using the HTTP method GET, for example. However, some resources actually store information or create additional resources. For example, if you have a blog, you might use the HTTP method POST to create a new blog entry. The "thing" to which your browser issued the POST method is a resource (some type of blog "factory") and the new blog entry is another resource.

The important thing to understand, though, is that REST actually encourages the use of more HTTP methods than what most web browser support (at least at the time of this writing in 2008). Most web browsers only support two HTTP methods, namely GET and POST. Yet, HTTP also defines the methods PUT, DELETE, OPTIONS, HEAD, TRACE, and CONNECT.

While all HTTP methods might be used by a RESTful web service, the ones that are really important are GET, PUT, POST, DELETE, and HEAD.

GET

GET is used to retrieve a representation (or, "stuff") from a resource. GET is widely used today for downloading web pages. However, it might be used to GET any kind whatever representation a resource may provide, including XML data.

HEAD

HEAD is similar to GET. The significant difference is that the representation is not returned. Rather, only the HTTP header with the various headers is returned. The HTTP protocol has a number of headers, such as Content-Length and the date the resource was last modified. Sometimes, it is useful to use HEAD to see if something has changed before deciding down transfer a large representation over the network.

PUT

PUT is used to store a representation at a resource. That sounds strange, but said another way, this is a way to perhaps upload a file and have it stored at a particular URI at the web server or to perhaps create a user account on a web forum. Imagine, if you will, creating a new blog entry that has some files attached. PUT would be the appropriate method to use to upload those files, especially if the client (or "user agent") knows exactly where those files should be placed. If one issues a PUT two times, then the second representation overwrites the first representation. This is entirely harmless if a file is uploaded two times, since the end result is the same file. However, if two different users issue a PUT to the same URI, the representation stored at a given URI will be the last one received.

DELETE

DELETE, as you can imagine, deletes information that one stores. If there is a resource that one would like to remove from the server, DELETE is the method one should use.

POST

POST is similar to PUT, and therefore confusing. POST also creates a resource, like PUT. The key difference is that POST is used when the server is in control of storing information, not the client. This is usually the case when posting a blog entry, for example. If the client wishes to create a new blog entry, it is the server that is responsible for storing the information in a database and assigning a unique value and/or URI to the newly posted content.

POST is also the appropriate tool to use when the operation does not result in the creation of a resource, but perhaps the invocation of some action. As an example, using a web-based form to transmit an email message would be an appropriate use of POST.

OK, that last sentence will raise a few eyebrows in the REST community. But, alas, what system exists where there are not some "things" that do something, other than store information? If one wishes to transmit an e-mail message, for example, POST is the method to use. In that case, some action is performed, but a new resource is not created as a consequence.

Safety and Idempotence

There are two other terms associated with REST that you should know, simply because they appear in all of the literate related to REST. Those are the words "safe" and "idempotent". These words do not come from Fielding's original PhD thesis on REST, but do appear in RFC 2616 and have been popularized through the book RESTful Web Services from O'Reilly.

The word "safe" means that if a given HTTP method is invoked, the resource state on the server remains unchanged. In theory, GET is always safe. No matter how many times you download this web page, the contents of it will not change due to your repeated downloads, since you cannot change the web page in that way. That sounds obvious, but if you build a RESTful web service that uses GET in such a way as to modify any state contained within a resource, then you have violated the rules.

PUT is not safe, because if you store something on the server, then you are creating a new resource or you are modifying a resource. (Of course, one might modify a resource to contain the same representation, but that is a corner case and not the general rule we apply to PUT.)

DELETE is clearly not safe.

HEAD is safe for all the same reasons that GET is safe.

So, what about POST? Some argue that POST is not safe. But, we argue that "it depends". If a POST operation is used to create a resource (e.g., a blog entry), then it is not safe. However, if POST is used to send an e-mail, then why would it not be considered safe? In the latter case, the state of the resource did not change. As such, it is safe.

The word "idempotent" means that, regardless of how many times a given method is invoked, the end result is the same. GET and HEAD are idempotent. GET and HEAD are both safe and idempotent, actually.

PUT is also idempotent. If you issue PUT 100 times, the resource state on the server is exactly the same as if you use the PUT method one time.

DELETE is also idempotent. If you delete a resource once, it is gone. One cannot delete it again and, if one tried, it would have obviously not make state changes to the resource, since there is no resource to change.

So, what about POST? As you can tell, POST is really the "problem child" for REST. It is somewhat ill-defined in the HTTP specifications and does not map perfectly to the concepts of REST. Most of the time, POST is not idempotent, as we will discuss below. However, if the server state is not changed as a consequence of issuing a POST, it is idempotent. In most cases, though, a POST is used to create or modify a resource, and often not idempotent.

Have you ever visited a web site to post an article or blog entry, or make a payment and accidentally press "submit" twice? Often, the server will accept that and perform the request two times, because POST is not idempotent. To be useful, though, one might design a means of using POST in such a way as to make it idempotent. There are a few non-standard mechanisms out there for that, the most common approach being to use POST to first create a new resource used to accept a subsequent POST method. Then, once the POST method is received for the given resource, the resource refuses to accept any additional POST requests.

This probably requires a more concrete example. Suppose you wish to post a blog entry. You might press the "post a blog entry" link, which might result in creating a resource called "http://example.org/blog/post/123" and your web browser is now showing a web form that allows you to type the contents of the blog. When you press the "submit" button, the HTTP POST is issued to the URL "http://example.org/blog/post/123" and, once that is received, and further posting attempts are rejected. If you had inadvertently clicked on the "post a blog entry" two times, two different blog posting resources might have been created (e.g., 122 and 123), but the first one (122) should be deleted automatically at some point, restoring the server state with no ill side-effects. But, since there are no standard procedures, then we cannot tell you exactly how to implement the logic. Hopefully, you get some idea.

REST and Multimedia Communications

So, how does REST relate to multimedia communications? REST is one more tool in the toolbox to enable communication between a number of different devices in the network. This could include, for example, a user's mobile phone that is communicating with a video display device. Perhaps REST might be the technology employed in the mobile phone in order to allow one to remotely increase or decrease the volume on an LCD panel or an Internet radio device.

REST might also be used between servers in order to exchange information. In any H.323 network, for example, a Gatekeeper queries a remote gatekeeper in order to perform address resolution. One could use REST for the same purpose.

REST Has Wide Applicability

The last sentence in the previous section highlighted something very important: REST can and will be used between various systems in the network in the future. So what is so important to note about that? Well, those systems may very well be from different vendors and/or implement REST interfaces that operate as different software release levels. Therefore, when designing a REST interface, one must be mindful to ensure that systems can communicate in such a way as to be forward and backward compatible.

The advantage of REST is that, through the use of HTTP, there is a uniform interface between various applications. Through the simple operations GET, HEAD, PUT, DELETE, and POST, virtually everything that two communicating devices want to accomplish can be.

That said, REST is not without faults. REST relies on HTTP and, quite often, carries an XML payload. Therefore, when two devices are communicating, versioning becomes an issue. The XML versioning and JSON versioning guidelines provide a means of addressing this issue. It is important to note here that versioning on a web server could be performed using URIs that contain versioning information. For example, Yahoo has a search API that looks like "https://search.yahooapis.com/WebSearchService/V1/webSearch". The "V1" indicate the version, which works perfectly well, since Yahoo! will likely only add more versions and all versions will be available simultaneously. However, when using various independent devices like mobile phones, LCD panels, or network servers not under the control of the equipment manufacturer, there may be a number of versions of any given interface employed in those devices. So, the XML versioning rules are quite important.

Another issue for REST is that is a resource on a server is generally a simple, independent "thing". But, what if a client needs to manipulate three different resources in succession in order to achieve a desired result? For example, perhaps a client needs to post a blog entry, upload a referenced file, and then request that the RSS feed be updated to include the new blog entry. What does the client do if the first operation succeeds, but the last one fails? REST does not have the concept of "transactions" and, indeed, if those operations are performed over a plurality of devices, it is a complicated problem. Still, some type of transaction support is necessary in some cases and achievable, but just not readily achievable.

Still, REST has its place in the world and is significantly simpler to understand and implement than SOAP or some other technologies. With REST, one normally just uses HTTP and includes XML in the message body when appropriate. It is a fairly simple concept, but provides a lot of functionality.