Using REST in Practice

Let's expand on the example quoted earlier involving our articles web service.

Reading a List of Available Articles

The list of available articles is a resource. Because the web service conforms to REST principles, we expect the service to provide a URL by which we can access this resource, for instance:

http://somedomain.com/articles/list.php

Because we are querying information, rather than attempting to change it, we simply use an HTTP GET request to the preceding URL. The server may return, for example, the following XML:

<articles>
    <article>
        <id>173</id>
        <title>New Concepts in Ajax</title>
        <author>P.D. Johnstone</author>
    </article>
    <article>
        <id>218</id>
        <title>More Ajax Ideas</title>
        <author>S.N. Braithwaite</author>
    </article>
   <article>
        <id>365</id>
        <title>Pushing the Ajax Envelope</title>
        <author>Z.R. Lawson</author>
    </article>
</articles>

Retrieving a Particular Article

Because this is another request for information, we are again required to submit an HTTP GET request. Our web service might perhaps allow us to make a request to

http://somedomain.com/articles/list.php?id=218

and receive in return

<article>
    <id>218</id>
    <title>More Ajax Ideas</title>
    <author>S.N. Braithwaite</author>
</article>

Uploading a New Article

In this instance we need to issue a POST request rather than a GET request. In cases similar to the hypothetical one outlined previously, it is likely that the server will assign the id value of a new article, leaving us to encode parameter and value pairs for the title and author elements:

var articleTitle = 'Another Angle on Ajax';
var articleAuthor = 'K.B. Schmidt';
var url = '/articles/upload.php';
var poststring = "title="+encodeURI(articleTitle)+"&author="+encodeURI(articleAuthor);
http.onreadystatechange = callbackFunction();
http.open('POST', url, true);
http.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
http.setRequestHeader("Content-length", poststring.length);
http.send(poststring);

Real World RESTthe Amazon REST API

Leading online bookseller Amazon.com makes available a set of REST web services to help developers integrate Amazon browsing and shopping facilities into their web applications.

Note

Amazon.com often refers to the REST protocol as XML-over-HTTP or XML/HTTP.

By first creating a URL containing parameter/value pairs for the required search parameters (such as publisher, sort order, author, and so on) and then submitting a GET request to this URL, the Amazon web service can be persuaded to return an XML document containing product details. We may then parse that XML to create DOM objects for display in a web page or to provide data for further processing as required by our application.

Tip

Amazon requires that you obtain a developer's token to develop client applications for its web services. You will need this token in constructing REST requests to Amazon's web services. You can also obtain an Amazon Associate's ID to enable you to earn money by carrying Amazon services on your website. See http://www.amazon.com for details.

Let's see this in practice by developing a REST request to return a list of books. Many types of searches are possible, but in this example, we request a list of books published by Sams.

We start to construct the GET request with the base URL:

$url = 'http://xml.amazon.com/onca/xml3';

We then need to add a number of parameter/value pairs to complete the request:

$assoc_id = "XXXXXXXXXX";   // your Amazon Associate's ID
$dev_token = "ZZZZZZZZZZ";   // Your Developer Token
$manuf = "Sams";
$url = "http://xml.amazon.com/onca/xml3";
$url .= "?t=".$assoc_id;
$url .= "&dev-t=".$dev_token;
$url .= "&ManufacturerSearch=".$ manuf;
$url .= "&mode=books";
$url .= "&sort=+salesrank";
$url .= "&offer=All";
$url .="&type=lite";
$url .= "&page=1";
$url .= "&f=xml";

Submitting this URL, we receive an XML file containing details of all matching books. I won't reproduce the whole file here (there are more than 5,000 titles!), but Listing 15.1 shows an extract from the XML file, including the first book in the list.

Listing 15.1. Example of XML Returned by Amazon Web Service

Clearly we can now process this XML document in any way we want. For example, Lesson 14, "Returning Data as XML," discussed how to use JavaScript DOM methods to select information from the XML document and place it in page elements added to the DOM of our document.