PUT yourself in a State of REST — How to GET the Web’s Architecture

Developing Custom VersionOne Apps 101 Series Guide

In the last couple of articles in this series, we explored the basic ideas behind HTTP,  Hypertext Transfer Protocol, and then last time, in The Evolution of the Web is Being YouTubivised, and it’s Linked, we looked at the web’s inventor Tim Berners-Lee’s vision of the web’s evolution as Linked Data.

But, to understand how the Linked Data project has grown up and continues to expand, we have to examine a vision by another pioneer of the early and modern web: Dr. Roy Fielding.

After we do, you’ll see why the title phrase “How to GET the Web’s Architecture” is not just a pun, it’s something you can do, thanks to Roy and his collaborators. Well, you can get a representation of the web’s architecture, at any rate.

In this article, you will

  • Read about why Roy Fielding described the web’s architectural style as REST — REpresentational State Transfer
  • Learn why the Uniform Interface of REST is crucial, both as a foundation for the Linked Data project, and as the bedrock of thousands of web APIs, including VersionOne’s REST APIs

Another frustrated soul trying to change the world

Roy Fielding’s doctoral dissertation from 2000 is named Architectural Styles and the Design of Network-based Software Architectures. It’s not really that long, and I recommend reading the whole thing, but he defined REST in Chapter 5: Representational State Transfer (REST), which itself takes about 15 minutes to read.

Roy was motivated to make this the subject of his dissertation because he was a co-founder of the Apache Server Project, the open source web server which still powers more than 60% of all web sites. He had been working on both the HTML and Uniform Resource Identifier (URI) standards since the early 1990s, and started to see what he considered improper use of the web’s standards become profligate.

He wanted to change that. He wanted people, especially other developers, to use the web properly.

The Central Principle

Here’s a big long quote from the Wikipedia entry on REST:

An important concept in REST is the existence of resources (sources of specific information), each of which is referenced with a global identifier (e.g., a URI in HTTP). In order to manipulate these resources, components of the network (user agents and origin servers) communicate via a standardized interface (e.g., HTTP) and exchange representations of these resources (the actual documents conveying the information). For example, a resource that represents a circle (as a logical object) may accept and return a representation that specifies a center point and radius, formatted in SVG, but may also accept and return a representation that specifies any three distinct points along the curve (since this also uniquely identifies a circle) as a comma-separated list.

At first, this can seem pretty abstract, and I do recommend both the Wikipedia article and chapter 5 from the link above, but I’ll make the concepts less abstract with a physical analogy that I’ve used in another blog about street addresses:

All resources, including documents, images, services, scripts, and stylesheets have universally unique address

Just like every building on a street, in a neighborhood, block, city, county, state, or country has a globally unique mailing address, so too does every piece of information available on the web have a unique address, except they are called URLs, or Uniform Resource Locators. More properly, URLs are a type of a more general concept, the URI, or Uniform Resource Identifier. I don’t care to make any further distinction for our purposes, but feel free to read the Wikipedia links for more information. We’ll use the term URL.

Examples of URLs abound

You’re well accustomed to URLs and can think of dozens:

Routing HTTP requests like routing the mail

All of the URLs above, when clicked, involve the concept or routing, and location, similar to the way your mail gets routed. That gets into the Domain Name System (DNS), and address binding. That’s beyond what I want to discuss, but remember that when you type an address to send an HTTP request to, it has to get routed through the internet’s communication systems in order to arrive at the remote location — just like paper mail needs to get routed and delivered.

Statelessness — the post office doesn’t remember your last recipient location, and neither does the web

Another big thing you’ll hear and read a lot about regarding REST is the concept of statelessness. This almost sounds like a paradox, since REST stands for REpresentational State Transfer. But, what it really means is that each time your browser initiates a request for a resource from a remote server, then that request should contain all the information necessary for the server to carry out the request properly. In other words, the server does not store any state specific to you and your past requests.

Consider that when you send a letter in the mail you always have to put an address on it, no matter how many times you have sent a letter to the same exact location. Why must you do that? Well, the list of possible mailing address is gigantic! And, different routes might be used to get your letter there. So too are the possible locations for internet addresses nearly endless, and so too might the route traveled be different.

Aside: Practically speaking, however, not all web applications get designed to obey the statelessness principle as a “hard and fast” rule. HTTP sessions and HTTP cookies are, strictly speaking, violations of this principle.

Uniformity of interface is crucial

When you put a stamp on a letter and place it in the mailbox, you are basically conforming to a “uniform interface”, or set of rules, that the postal system defines. It’s a pretty small set of rules, at that. It’s something like this:

  • Place a letter with an address and proper postage in your mailbox
  • A mail carrier will pick it up and take it to an office for routing and delivery
  • If your mailbox has enough space, the mail carrier will place letters for you into it that other people addressed to you
  • And, if you have special instructions, you can affix special “headers” to a letter or package by going to an office

The web’s own uniform interface is defined by the small, constrained set of HTTP verbs that we looked at a couple articles ago. Web servers that make resources addressable at URLs expect browsers to communicate with HTTP requests using those standard verbs like: GET, POST, PUT, DELETE, OPTIONS, PATCH, and a handful of others.

Why the uniform interface empowers the web, you, me, and Haiti

Last time we saw Tim Berners-Lee’s vision of the Linked Data web. But, he also came back to TED the year after and gave a five-minute, visually stunning talk called The year open data went worldwide as a result to his call to start sharing data.

Here’s an excerpt from his talk:

Here focusing in on Haiti. The map of Port au-Prince at the end of 2009 was not all it could be, not as good as the map of California. Fortunately, just after the earthquake, GeoEye, a commercial company, released satellite imagery with a license, which allowed the open-source community to use it. This is January, in time lapse, of people editing … that’s the earthquake. After the earthquake, immediately, people all over the world, mappers who wanted to help, and could, looked at that imagery, built the map, quickly building it up.

We’re focusing now on Port-au-Prince. The light blue is refugee camps these volunteers had spotted from the [satellite images]. So, now we have, immediately, a real-time map showing where there are refugee camps — rapidly became the best map to use if you’re doing relief work in Port-au-Prince. Witness the fact that it’s here on this Garmin device being used by rescue team in Haiti.

There’s the map showing, on the left-hand side, that hospital — actually that’s a hospital ship. This is a real-time map that shows blocked roads, damaged buildings, refugee camps — it shows things that are needed [for rescue and relief work].

So, if you’ve been involved in that at all, I just wanted to say: Whatever you’ve been doing, whether you’ve just been chanting, “Raw data now!” or you’ve been putting government or scientific data online, I just wanted to take this opportunity to say: Thank you very much, and we have only just started!

Here’s a video clip on YouTube that shows, in 53 seconds, the dramatic improvement of free, public data available after volunteers started sharing data, as Tim asked them to do in 2009. Having worked at the Centers for Disease Control and Prevention here in Atlanta, I can attest how important this kind of information is for rapid outbreak response.

That kind of mass collaboration at scale would not have been possible without the OpenStreetMap REST API, built upon the open standards and principles laid down by people like Tim Berners-Lee and Roy Fielding.

There have been thousands, and thousands of technologies that have come and gone since the internet, and later the web, were born. But, it’s largely because of  world-wide adoption of the standards of URLs and HTTP, with its “RESTful” uniform interface  — and mostly just GET and POST therein — that have fundamentally transformed how we live and communicate in our world.

When Ian didn’t listen

Also at TED, an entrepreneur named Ian Ritchie told his own five-minute story, The day I turned down Tim Berners-Lee:

I took a system to a trade show in Versailles near Paris in late November 1990. And I was approached by a nice young man called Tim Berners-Lee who said, “Are you Ian Ritchie?” and I said, “Yeah.” And he said, “I need to talk to you.” And he told me about his proposed system called the World Wide Web. And I thought, well, that’s got a pretentious name, especially since the whole system ran on his computer in his office. But he was completely convinced that his World Wide Web would take over the world one day. And he tried to persuade me to write the browser for it, because his system didn’t have any graphics or fonts or layout or anything; it was just plain text. I thought, well, you know, interesting, but a guy from CERN, he’s not going to do this. So we didn’t do it.

In the next couple of years, the hypertext community didn’t recognize him either. In 1992, his paper was rejected for the Hypertext Conference. In 1993, there was a table at the conference in Seattle, and a guy called Marc Andreessen was demonstrating his little browser for the World Wide Web. And I saw it, and I thought, yep, that’s it. And the very next year, in 1994, we had the conference here in Edinburgh, and I had no opposition in having Tim Berners-Lee as the keynote speaker.

So that puts me in pretty illustrious company. There was a guy called Dick Rowe who was at Decca Records and turned down The Beatles. There was a guy called Gary Kildall who went flying his plane when IBM came looking for an operating system for the IBM PC, and he wasn’t there, so they went back to see Bill Gates. And the 12 publishers who turned down J.K. Rowling’s Harry Potter, I guess.

On the other hand, there’s Marc Andreessen who wrote the world’s first browser for the World Wide Web. And according to Fortune magazine, he’s worth 700 million dollars. But is he happy?

What do you imagine building?

Is there something you’d  like to build using the web? Can it have a REST-based API like the OpenStreetMap project?

Next up, in Understand How and Why REST APIs Work — Demonstrated with the VersionOne Data API, we peer into the VersionOne REST Data API and understand what a REST API actually looks like, and how it is built atop all the concepts we’ve already studied in this series.

This entry was posted in How-To. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *