We're starting a new series today.

For some reason, learning about REST was a bigger struggle for me than it ever needed to be. I'm not exactly sure what that was. Maybe it's because I spent so much of my life writing client applications, not web applications. Maybe it was because (read quickly now) I was getting up to speed on the whole HTTP programming thing at the same time I was learning Ruby at the same time I was learning Rails and it was right after that I went to the first RailsConf and everyone got excited about REST and I smiled like I understood so I wouldn't look like an idiot but really I had no idea what was going on... Whew.

If you're trying to make sense of what REST on Rails is all about, then this series is for you.

People who are experts in HTTP, HTML, and REST might nitpick with my simplified terminology so I can focus on the topic at hand. If that's you, I don't want to hear about it, because this series isn't for you anyway :-)

Square One

Let's begin at the beginning. How does a web browser work? Before trying to build websites with Rails, I used to think it was something like this:

• I type in a url into the address bar, or click on a link
• The browser makes an "http request" (whatever that means) and gets HTML code in response
• The browser renders the new HTML onto the page

And that was pretty much it. And I never really thought about how forms worked, either. I just figured they were a variant of the above.

In reality, the HTTP protocol includes exact instructions on how a browser should send its request to the server. HTTP is totally different from HTML, which happens to be the markup language chosen to represent the page content. It turns out that HTTP enables the browser to retrieve all kinds of information from the server, beyond simply getting an HTML page or submitting form data. In fact, HTTP actually allows for eight different kinds of requests to be made to the server. However, we are most familiar with these two kinds of requests:

• A "GET" request: get the contents of some resource on the web; the resource is uniquely identifed by a URL;
• A "POST" request: send a package of data to a URL to create a new resource.

Square Two

See how I've slipped in the word "resource" when you weren't expecting it? Well, this is where my first, critical turning-point in thinking came in trying to understand REST: thinking of the web as a collection of resources, not "web pages". What do I mean by that?

Yesterday, I went on amazon.com and looked at some products I could buy. I also read some articles on Wikipedia. I read some news headlines on CNN. Then I checked the latest NHL standings to see just exactly how far Chicago is out of the playoffs.

If you want to understand REST, you have to stop thinking of these things as web pages. Let's take a Wikipedia article as an example. It's not just a web page. It's a resource - in my case, a short biography of Archimedes. I happened to use a web browser to access that resource, so the web browser requested an HTML representation of that resource, because rendering HTML is only way web browsers can display resources.

I know this is weird at first. Isn't the Archimedes article a web page? No. I asked for the HTML representation for a resource held by Wikipedia, a resource that can be identified by the URI "//en.wikipedia.org/wiki/Archimedes". Wikipedia could have chosen to represent that resource in any number of ways - with a PDF, or perhaps as a .jpg picture. Maybe they offer all of those. But Firefox used a GET request that specified that the resource should be provided by the server as HTML, so that's what I got.

Another example: my plane reservation is a resource held by United Airlines. They let me get to that resource in many ways: as an HTML page, but they can also send my reservation information as a text message to my cell phone. Or they could send it to me in plain text in an email. Or I could call them up on this old device and they would tell it to me verbally. Same resource, multiple representations.

So I hope it's obvious now: my airline reservation is not just a web page. It's a real resource that (fortunately for me) can be rendered whenever I choose with HTML, and I can use my browser to request that representation and render it onto my screen.

Square Three

Ok, once you can accept that the web is actually a huge collection of resources that can be rendered in multiple ways, and that an HTML rendering is just one of those, then there's one more concept I want you to grasp before we stop today. Resources aren't just single things like biographical articles, or an airline reservation, or a sports statistic. Some resources are collections of other resources. A list of holidays can be a resource. A list of friends can be a resource. A series of blog posts can be a resource.

Now that you understand what resources are, tune in next time when we talk about how HTTP enables the creation, reading, updating, and destruction of resources. (Rats, I think I just gave it away.)

Questions? Suggestions? Flames? Leave a comment and tell me.