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

Tweet
This entry is part 1 of 2 in the series REST - Can You do More than Spell It?

REST - Can You do More than Spell It?

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

REST - Can You do More than Spell It?

REST – Can You do More than Spell It? Part 3 >>

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • http://facebook.com/md2perpe Per Persson

    “Some people tend to relate the PUT to a create and the POST to an update.”
    I’d say that most people knowing HTTP do the opposite: they relate PUT to update and POST to create.

  • dave f

    Everything was great until the end you mention PHP. I suddenly lost interest.

    • http://www.php-tip-a-day.com Greg Bulmash

      @dave f: You’re reading this on a site called PHP MASTER and you suddenly lost interest when he mentioned PHP?? Are you just being a troll or are you really that unobservant?

  • http://www.php-tip-a-day.com Greg Bulmash

    Just had to implement a REST based web service, and when the consumer started having problems with it, I thought I’d done it wrong. But the more I researched REST, it seemed there wasn’t an exactly right way to do it and I was doing it as “right” as you can do with REST.

    Nice to see confirmation of this.

  • Nilesh

    Nice explanation on PUT vs POST

  • Lakshmi narasimhan

    Thanks for the quick and light weight intro to REST. Looking fwd to the next in series

  • http://cdtwebsolutions.com Clint

    Thanks for the article.. looking forward to the next three parts. I like the idea of REST but I would rather use only POST (through cURL) and define get/put/post/delete through the URI.. anyone see any definitive problems with doing it this way? Is it not REST any longer if I do it this way? Thanks for your input.

    • Alex

      I am new to web services and REST, but unless I am misunderstanding, these are two separate issues, no?
      GET, PUT, POST and DELETE would be part of the URI used by the client (in most cases a different server, quite possibly using cURL to communicate) accessing the RESTful web service.
      When using cURL, the POST and GET options are the method by which the URI (and any additional data such as an XML stream) are transmitted to the web service (no matter if it is a RESTful service or not), and I believe POST is strongly recommended for most situations.
      Does that sound like I am understanding this correctly?
      Also, thanks for the article. I really enjoyed it and am looking forward to the rest of the series.

  • Dragan

    And thanks for being funny by stereotyping East Europeans.

  • David Shirey

    Couple of points. from the bottom up, I would like to –
    Dragan – Apologize to East Europeans for any insult I may have applied, although in this case I think it was more of a compliment. No reason everything has to go through 10 year FDA trials. Let’s give it a shot and see if it works.

    Alex – sounds like you do understand things correctly. Things get a bit woozy when you try to differentiate services and REST. It is like trying to define what it is like to be Catholic. The essence of REST is that everything is a resource (a page), and each step in the process doesn’t carry any info about previous steps (stateless). Everyone things of services as being SOAP, but there is a simpler way, with less overhead, and that is REST.

    Clint – No problem, REST is not about PUT or POST, it is about the everything is a resource and being stateless. I can totally understand using POST vice PUT. No problem.

    Lakshmi, Nilesh – Thanks for your kind words. I love to write things that people find interesting. Or that attract babes. Either one.

    Greg – Glad you feel validated. REST is not one way or another, but a way of thinking. I agree.

    Per – interesting thought. let me think about that.

  • Tomasz

    Everything was great until when you disrespected Eastern Europeans. I suddenly lost interest.

    • dave Shirey

      You are completely correct. It was inappropriate and I sincerely apologize for how it made you feel It will not happen again. Take care.

  • jj

    Man, appreciate humor in your tutorials, but I have a question, for your example of when to not use POST for creating an account, wouldn’t it not matter because the db would have retreived the user name to ensure no duplicated user names allowed to register?

    • dave Shirey

      Sorry it took a while for me to get back to you. To be honest I am having a very difficult time re-entering the non-holiday world.
      I suppose you are right, the app should recognize that this user has already registered, although the Post by itself would not do that. I think the two main reasons for being careful with the POST (vice PUT) are idempotence and your ability to control the URL that is going to be assigned to this entity. Both are useful things but like Stolli and Belvedere, you have to know when it is appropriate to use each and not just assume they are equivalent.

  • http://www.igutu.com James

    Really interesting article. Well written, and passed the message very well.

    • Dave Shirey

      Thanks for the kind words. Even though the article was published almost a year ago (another year of my life shot to hell), it’s never too long to thank someone for a compliment.