REST – Can You do More than Spell It? Part 1

Thousands of years ago when we first started building web pages, things were very simple. You’d put some text on the page, maybe even an image, and that was pretty much it. But today it’s a whole different ball game. Instead of static pages there’s the dynamic applications we’ve come to depend on. And so, how these applications are designed to communicate becomes very important. In this series I’ll introduce you to the REST architecture style. In this article I’ll help you to understand exactly what it is, and later I’ll show you how it can be implemented in a PHP environment.

What is REST?

REST is a set of principles that define how a server and client can communicate with each other (and external resources) in a simple, straightforward, and robust manner. Though you’ll often see the words “REST” and “architecture” together, REST is not a specific architecture. I like the words used by Dr. M. Elkstein in Learn REST: A Tutorial when he called it an “architecture style.” REST provides definite guidelines on how things should be built but does not insist things be built a certain way using certain building blocks.

In many references you will see REST and SOAP both mentioned as competitors. That is not true. SOAP is actually a protocol, not an architecture style. What REST can be compared against is SOA and RPC. All three are examples of web service styles, each with their own conceptual focus. RPC is focused around operations, SOA around messages, and REST around resources.

The ideas behind REST have been around for a while, first appearing in the doctoral dissertation of Roy Fielding, one of the developers of the HTTP protocol. Indeed, the influence of REST on HTTP, and thus on the Internet itself, is clearly visible. But REST isn’t a standard or a protocol; there are no W3C documents to outline what it should be, and there are no version numbers to date it. If you do REST, you will certainly end up doing things a certain way, but that is not the same as saying it is a standard.

REST stands for REpresentational State Transfer, and while this meant nothing to me the first time I saw it, Fielding had very definite ideas about its meaning.

• Representational refers to the fact that when you access something via the web what is returned to you is a representation of the object, not the actual object itself. If you go out and get a list of addresses, you could get back an XML data stream, not the actual database that stores the addresses.
• State refers to the belief that no session state should be kept on the server. Each request from the client should contain all of the necessary information for the server to understand the context of a request without referencing a previous transaction. All state is maintained by the client.
• And Transfer refers to how data is shared across a network between clients and servers.

Principles of REST

So if REST is a set of principles, what are those principles?

Identify Everything as a URI – Everything in REST is a representation of some resource which can be identified by a unique URI (uniform resource identifier). This is the way the web itself is designed and it ensures a simplicity that is not available if resources are given a variety of different nomenclatures.

Hypermedia as the Engine of Application State – One of the beauties of the web is the ability to link from one page to another, so why not use that as the basis for all state transfer? Clients transition through a web application only through actions within the resource, such as hyperlinks.

Requests are Stateless – Central to REST is the idea of statelessness. That is, each request handled by the server can be done without knowing anything about any previous request. Or to put it another way, the client supplies all necessary information in the request needed by the server to fulfill it.

Standard Protocol Usage – there is nothing in REST that requires it to use HTTP. And yet, most of the time when you see a REST system it is built on HTTP. The reason for that is that HTTP uses four basic operations (GET, PUT, POST, and DELETE) to do all operations, and REST gravitates towards a small, standardized set of operations.

In general, REST encourages simplicity and standardization, attempting to let the already existing protocol features do much of the heavy lifting and eliminating the need to re-invent these functions with programmer written operations. Although much of the web application development done today takes an RPC or SOA approach, there is a growing interest in using the more simple and yet robust style that REST advocates.

PUT vs. POST

As I’ve noted above, REST is not a true architecture and it doesn’t force you to use certain tools or protocols. But most implementation use HTTP, primarily because of it’s simplicity. Every protocol has operations defined in it that perform the CRUD (Create, Retrieve, Update, and Delete) work required when data is involved. HTTP uses the four basic operations GET, PUT, POST, and DELETE to do it’s CRUD work.

As you might expect, GET retrieves data for you, and DELETE deletes data. And that brings us to PUT and POST. Discussing either of these, but especially POST is a little like discussing religion or politics; you are bound to upset someone. But here goes…

Some people tend to relate the PUT to a create and the POST to an update. But I honestly think that is an over simplification, sort of like saying that the Dark Side of the Force is just what you experience on a day when you are a bit grouchy. In reality there are significant differences between the two methods.

First, let’s start with the term “idempotent.” This is not to be confused with a similarly named, very serious medical condition for men which can only be treated by a number of drugs, none of which are street legal outside of Eastern Europe. Idempotent means that if you apply the operation multiple times, you will get the same result as if you had just applied it once. What’s the difference? It’s the difference between buying one authentic Dolly Parton figurines or five if you are shopping online and hit the Enter key a few times too often. As it turns out, GET, PUT, and DELETE are all idempotent. POST is not.

The only way you can do the same operation multiple times and not have it screw everything up is to transmit all of the data associated with the resource when you request the operation. Hence, that’s what PUT does. The server receives all the data available and completely rewrites the resource. It doesn’t matter whether the resource is already there or not; you are completely replacing it so create and update is treated the same.

POST, on the other hand, is not idempotent. If you do it multiple times, multiple things will happen. For example, if you are creating a new user sign on and you use a POST, you are going to create a new account every time that you hit Enter. POST requests only require some, but not all, of the data associated with the resource. In fact it’s a very good if the data you are sending represents an addition to a resource that already exists, such as adding a comment to a blog post or an update to a trouble ticket. You follow me, slick?

Second, since REST is a resource-oriented architecture style (opposed to message-oriented as SOA is and operation-oriented as RPC), let’s look at this in terms of what is happening to the resource. PUT, an idempotent operation, affects the URI specified in the request. That is, it updates the resource at the URI that is provided by the client. POST affects a URI that is created and named by the server. The resource is updated with the data passed from the client, but the resource is separate and distinct from the client-named URI.

A good question to ask when you are arguing with yourself about PUT vs POST is who should be naming the URI, the client side or the server? Another way to put it is whether you want to retain control over the URI or farm it out let the server create related URI’s. A blog post could be created with POST example.com/blog. The server would create the entry with ID 42, which would then be available as example.com/blog/42. Alternatively, a blog post could be created with PUT example.com/blog/42 if the resource didn’t already exist (in which case it would be replaced). The naming of the resource example.com/blog/42 was left up to the server with POST, and up to the client with PUT.

Summary

REST is not a set way of doing things, it’s a state of mind based on a couple of simple principles: treat everything as a resource identified by a URI, use hyperlinks to move from one resource to another, treat everything as stateless, and use a standard protocol with generic operations. The advantage of REST over SOA or RPC is simplicity and speed (because there is less overhead both in what you have to build and in its processing) while still allowing you to build a solid and robust system. Most REST applications use HTTP (because of it’s simplicity) and so it is important to understand the difference between the PUT and POST methods.

In the next spine-tingling chapter of this saga, our hero and his plucky sidekick will show you how PHP fits in with all this. How can PHP be used with REST, and in particular how it interfaces with HTTP. I don’t know about you, but I’m stoked! I can’t wait to learn more about this exciting technique.

Image via littlesam / Shutterstock