Get Started With REST

Current revision

For a long time, I read about "RESTful APIs" and had no idea what that term meant. The API part means Application Programmer Interface, a way for coders to get data from a website within their own programs. That much I knew. But as for the REST part, that was less familiar to me.

As a programmer, being clueless doesn't stop me from playing around. What I observed when I tested some APIs that use REST is that there wasn't much to it at all.

REST isn't a big deal. In fact, it's all around us! When you go to a web page, you're sending a REST request. When you search the web, yeah, that's using REST, too.

This tutorial, originally submitted by Webmonkey contributer Adam Duvander, is a wiki. Got extra advice? Log in and add it.

So, What is REST?

REST is a way of interacting with resources on the web via a plain ol' URL. It stands for REpresentational State Transfer, a description that's far more confusing than what REST actually is.

A basic web page is an example of a REST resource. When we access the page with our browser, a GET request is sent behind the scenes. GET is the most common action used in REST. Many APIs only allow reading data, not writing data. These APIs that only allow their users to retrieve data only implement GET.

The other popular action in REST is POST, which adds data to the service. For example, when a user fills out a form on a website and clicks submit, POST is often used.

Two other common actions associated with REST are PUT and DELETE. However, the implementation of these last two actions is spotty, so they are less likely to be used.

Example REST Request

Let's say you wanted to get some data from a fictitious website that lets people periodically send short messages. If this service had a RESTful API, we might be able to grab the latest messages with this URL:

api.example.com/messages

If we wanted a specific user's messages, we might use this URL:

api.example.com/messages?u=username

As you can see, this is a lot like browsing the web itself. One of the main benefits of REST APIs is that we're very familiar with the format of the request.

Example REST Response

There is no rule about what format a REST request returns. In the case of the web, we send HTML to a browser. Many APIs return XML and other standard formats. Some even give you options for what format you want.

Let's say we're wanting a response from the latest messages request above. In XML, it might look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<messages>
  <message>
    <date_created>Mon May 15 02:45:00 +0000 2008</date_created>
    <user>webmonkey</user>
    <text>Eating a banana and writing some code</text>
  </message>
  <message>
    <date_created>Mon May 15 02:44:00 +0000 2008</date_created>
    <user>anotheruser</user>
    <text>I think it might be time to go to bed</text>
  </message>
  <message>
    <date_created>Mon May 15 02:43:00 +0000 2008</date_created>
    <user>someone</user>
    <text>What the heck is REST?</text>
  </message>
</messages>

This XML response can then be interpreted by an XML parser. That may sound complicated, but there's good news: most languages have one built-in. Also, your browser may display raw XML in a tree format, so you can understand what your program will be parsing.

Other Common Response Formats

The above example uses XML, but there are a number of common formats that APIs use to return data.

RSS - Really Simple Syndication is commonly used to see updates from weblogs. The format is especially useful for types of data that include dates.

JSON - JavaScript Object Notation has become popular along with Ajax, which relies heavily on JavaScript. JSON results can be converted to a JavaScript object with a single command in JavaScript. A controversial format as it allows cross domain requests without warning the user. However this is also it's power, as it allows multiple services to be combined at the client end in a transparent fashion and without requiring extra server side scripting.

Serialized PHP - Results be converted into a PHP object with a single command.

CSV - The comma separated values format has data that you might see in columns of a spreadsheet. me

Examples of Sites with REST APIs

• Yahoo HTTP Geocoder

• Google HTTP Geocoder

• del.icio.us

• Twitter

• YouTube

• Upcoming

• This page was last modified 07:05, 21 August 2008.