REST for the Rest of Us

This article is intended to be an explanation of REST for a non-technical audience. In particular, it's meant for people who perhaps have heard the ubiquitous phrase "software as a service" but who are otherwise not familiar with the working of the Internet.

I'd like to give credit for helping me sort out my thoughts on this article to a semi-famous essay How I Explained REST to My Wife. It takes a more roundabout conversational approach, but covers quite a few deep insights into REST.

The first thing you should know about the web is that there's no web. In reality there are millions of computers around the world connected by a sophisticated addressing system. All the content on these computers--web pages, images, digital video, streaming audio--as well as certain processing tasks, are resources.

The term "web" is simply a metaphor to emphasize that all these computers are connected and discoverable. The architecture of this "web" is based on REST, which stands for REpresentational State Transfer. It's a somewhat obscure way of saying that the state (like a snapshot) of the data that describes a resource can be represented and transferred in standard formats. It sounds obvious, but the web needs basic rules.

REST is simple, because it's not a programming language, library, or platform, but a design, an architecture. All it means is that you can access a resource on the web with a request, it's RESTful. So the term RESTful can cover a large swath of exceedingly different web services. It's often hard to say exactly what makes an application RESTful web service. This is how I'd explain it to a lay person.

Until fairly recently, the resources people wanted were typically files: web pages (HTML files), images (JPG and GIF files), audio (MP3 and WAV files). However, more recently, resources have been tasks such as reading activity feeds (e.g. Facebook posts), or database searches (finding products in online catalogs), or accessing local weather data. Resources can also be computing services, like file storage and backup, or performing large computations in the cloud. These latter services are what is commonly referred to as "software as a service."

However, thinking in terms of data or processing tasks can be a little abstract, so for the purpose of explanation, I like to think of resources as pizza. After all, if you can order a pizza on the web, it must be a resource.

Every resource on the web has an address called a URL. You can think of it as the street address or phone number of the pizzeria. It starts out specifying a more general area, then becomes more specific--just like a phone number: area code, local exchange code, and last four digits of the specific phone.

Here are the operations you can perform on resources on the web:

• You can POST a pizza by ordering it--thus creating one. The purpose of POST is to create a new resource.
• You can PUT pepperoni, or other toppings on the pizza, by changing an existing order. The purpose of PUT is to change or update data in an existing resource.
• You can GET a pizza when your order is ready. The purpose of GET is to retrieve a resource.
• You can DELETE a pizza by canceling the order. The purpose of DELETE is to remove a resource.

These four verbs are the only operations used in RESTful web services. REST services use one of these verbs plus the URL to access data or a processing service.

Whenever you click a link on a webpage, the web browser makes a GET request on the address contained in that link. The address is also called a URL or Uniform Resource Locator--because its purpose it to locate resources.

Here's a very simple example. Suppose a friend sends you an email with a link to a YouTube video. If your friend clicked "share," YouTube provides a short version of the URL:

http://youtu.be/o0MIFHLIzZY

Let's break this down: The first part of the URL (youtu.be) is a shorthand address that redirects the browser to the YouTube home. Then there is a slash, followed by a cryptic code (o0MIFHLIzZY). This is the unique resource ID of the video. (That is, the video is a resource, and every resource needs a unique ID.)

By clicking this link, you're directly accessing (that is, GETting) the resource by its direct address.

But there are many ways to access data on the web. YouTube also allows you to access the same video this way:

http://www.youtube.com/watch?v=o0MIFHLIzZY

Using this form, you provide the regular URL for YouTube (www.youtube.com), then a slash followed by 'watch'. This accesses the watch service, an application that plays a video if you provide an ID.

The way you provide parameters in a URL is to add a '?' followed by parameter_name=parameter_value. In this case it's 'v= o0MIFHLIzZY'; the parameter name is 'v' and the value is the resource ID.

Specifying parameters is one way to provide information to web services. It's the typical way to provide information to web search applications such as Google search.