XML Reference Guide

If you come right down to it, "web services" have been around for a long, long time. In fact, you could probably call a simple web page a "web service" request, in that you're making a request over the web and getting back a response with some kind of information in it.

Of course, if you've been around what now passes for "web services" for any length of time, you've probably discovered that it's a whole lot more complicated than that. Yes, standard after standard has defined formats and SOAP messages and protocols that have made the process of making a simple web service request into an ordeal.

But it doesn't have to be that way.

Enter REST. REpresentational State Transfer is a funny name for what is essentially the idea of carrying through on the idea that all information on the 'net can be referenced by a URL. For example, we you may know that Amazon information can be found at http://www.amazon.com. You may even know that Amazon's XML books can be found at http://www.amazon.com/exec/obidos/tg/browse/-/4052/. REST extends this idea to web services. For example, if you were going to make a SOAP request to the Amazon Web Service for XML books, you'd try a request something like:

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <namesp1:KeywordSearchRequest xmlns:namesp1="urn:PI/DevCentral/SoapService">
            <KeywordSearchRequest xsi:type="m:KeywordRequest">
                <keyword>dog</keyword>
                <page>1</page>

                <mode>book</mode>
                <tag>webservices-20</tag>
                <type>lite</type>
                <dev-tag>000000000000000</dev-tag>

                <format>xml</format>
                <version>1.0</version>
            </KeywordSearchRequest>
        </namesp1:KeywordSearchRequest>
    </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

And, of course, you'd need to create an application that will send this SOAP request as an HTTP POST. It'll also have to receive and intepret the response, which looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
  xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:xsd="http://www.w3.org/1999/XMLSchema">
    <SOAP-ENV:Body>
        <namesp1:KeywordSearchRequestResponse xmlns:namesp1="urn:PI/DevCentral/SoapService">
            <ProductInfo>

                <Details url="http://www.amazon.com/exec/obidos/redirect?tag=your-assoc-tag%26creative=78997987%26camp=2025%26link_code=xm2%26path=ASIN/B00005O5DJ">
                    <Asin>B00005O5DJ</Asin>
                    <ProductName>Cats & Dogs (Full Screen Edition)</ProductName>
                    <Catalog>DVD</Catalog>

                    <Directors>
                        <Director>Lawrence Guterman</Director>
                    </Directors>
                    <TheatricalReleaseDate>04 July, 2001</TheatricalReleaseDate>
                    <ReleaseDate>16 October, 2001</ReleaseDate>

                    <Manufacturer>Warner Studios</Manufacturer>
                    <ImageUrlSmall>http://images.amazon.com/images/P/B00005O5DJ.01.THUMBZZZ.jpg</ImageUrlSmall>
                    <ImageUrlMedium>http://images.amazon.com/images/P/B00005O5DJ.01.MZZZZZZZ.jpg</ImageUrlMedium>
                    <ImageUrlLarge>http://images.amazon.com/images/P/B00005O5DJ.01.LZZZZZZZ.jpg</ImageUrlLarge>

                    <ListPrice>$26.98</ListPrice>
                    <OurPrice>$22.99</OurPrice>
                    <SalesRank>1,883</SalesRank>
                    <Lists>

                        <ListId>1FRDG9GR8J18E</ListId>
                        <ListId>36DOYMKRQYHXI</ListId>
                        <ListId>184A0KOYBA5RQ</ListId>
                    </Lists>

                    <BrowseList>
                        <BrowseNode>
                            <BrowseName>Feature Film Family</BrowseName>
                        </BrowseNode>
                    </BrowseList>

                    <Media>DVD</Media>
                    <NumMedia>1</NumMedia>
                    <Features>
                        <Feature>Color</Feature>

                        <Feature>Closed-captioned</Feature>
                        <Feature>Animated</Feature>
                    </Features>
                    <MpaaRating>PG (Parental Guidance Suggested)</MpaaRating>

                    <Availability>Available</Availability>
                    <Upc>085392125326</Upc>
                    <Reviews>
                        <AvgCustomerRating>3.40741</AvgCustomerRating>

                        <CustomerReview>
                            <Rating>4</Rating>
                            <Summary>a movie that's fun for the whole family</Summary>
                            <Comment>Let's face it, there are very few movies that don't drive a parent insane when they are viewed dozens of times, but this is one of them. I've seen this countless times and still don't mind it. The story of the hidden war between cats and dogs is a hoot, whether or not you actually prefer one species over the other, and the jokes and one-liners are hysterical. Like the best cartoons, there are jokes that make the kids laugh and jokes that make the adults laugh. The voice talent is superb, the human actors are very good (though poor Jeff Goldblum just seems to play himself anymore), the special effects are impressive and each scene works -- from the elaborate opening sequence to ninja cats and a visit to Dog Headquarters.<P>As for this DVD edition, the special features are pretty good. The film can be heard in English or French with English, French or Spanish subtitles. There are two featurettes: a 13-minute HBO First Look and a 6-minute special fx review. You can also compare storyboards of the ninja cat scene to the film, and the commentary track, featuring the director, the producer and the production designer, is very entertaining -- the participants even try to make the case that this movie is "like The Matrix"! I was prepared to give the DVD 5 stars until I realized that in very small print on the back of the box it says that the enhanced features on the DVD (including an alternative ending, an artwork gallery, screen savers and wallpaper) do not work on a Macintosh computer. Lame. Otherwise, though, this is a fun movie with entertaining DVD extras.</Comment>

                        </CustomerReview>
                        <CustomerReview>
                            <Rating>4</Rating>
                            <Summary>"Cats and Dogs" is a cute flick!</Summary>
                            <Comment>"Cats and Dogs" is the story of scientist Professor Brody (Jeff Goldblum) who is working on a cure for all dog allergies. It's up to the dogs to protect his work from the evil cats lead by Mr. Tinkles (Sean Hayes). The cat's plan: to reverse the chemical for curing dog allergy to making it so when humans take it, they will be allergic to all dogs. Then cats will rule the world. But instead of the dog leader Agent Butch (Alec Baldwin) getting a professional replacement for retired agent Buddy, he gets a young beagle puppy, Lou (Tobey Maguire), instead.<P>Has a pretty simple plot with some hilarious parts. Yet very stupid, with the animation very, very obvious like the 'ninja kitties'. Reminded me a lot of "102 Dalmations" except this movie has James Bond 007 thrown in.<P>But the biggest reason for giving this movie 4 stars is the voice talents from stars Alec Baldwin (one of my most favorite actors in his role in "The Hunt for Red October"), Tobey Maguire, Sean Hayes, Susan Sarandon (Played with another one of my favorite actors Kevin Costner in "Bull Durham"), Joe Pantoliano ("The Matrix", "The Fugitive", and "U.S. Marshals"), and Charlton Heston ("Ben Hur", "Ten Commandments" and "Planet of the Apes"). It was pretty fun for me to watch the movie and guess whose voice was whose. Got most of it correct. The other reason for giving it 4 stars was the humor for some of the humor was funny, others not. Favorite parts are:<P>Sean Hayes as Mr. Tinkles when forced to where a bonnet: "Does evil where a bonnet?"<P>Jeff Goldblum as Professor Brody, thinking there's a burglar in the house: "I've got a mitt and I'm not afraid to use it."<P>Alec Baldwin as Butch, when Lou (Toby Maguire) tries to eat an dynamite disguised as a cookie: "That would have been the shortest assignment in history." And more but can't write it all down.<P>All-in-all, a pretty cute flick for maybe young kids and adults, not much for teenagers I think.</Comment>

                        </CustomerReview>
                        <CustomerReview>
                            <Rating>4</Rating>
                            <Summary>THE FUR FLIES</Summary>
                            <Comment>What a strange movie! It has some really funny scenes and some great dialogue. Being a person who likes both cats and dogs, although favoring the felines, it was amusing to see how the cats were portrayed so villainously. The heroic dogs of course were lovable, particularly Lou, Butch and Ivy. The opening sequence had my wife almost choking on laughter. The catapult (play on words here) in the beginning is truly funny.<BR>The effects overall are astounding in that there are times when Butch really looks like Alec Baldwin, who provides the voice. One can almost see Toby Maguire too in Lou. The human actors (Jeff Goldblum, Elizabeth Perkins) are cartoonish but appropriately so in such a far out film.<BR>"Cats and Dogs" moves well, and one can't help but find it a great way to spend ninety or so minutes. Kids and adults both should love it. Not a great movie, but it is a lot of fun.</Comment>

                        </CustomerReview>
                    </Reviews>
                    <SimilarProducts>
                        <Product>B00003CX5P</Product>
                        <Product>B00003CXI1</Product>

                        <Product>B000065U1N</Product>
                        <Product>B00005JKQZ</Product>
                        <Product>B00005K3OT</Product>
                    </SimilarProducts>

                </Details>
                <Details url="http://www.amazon.com/exec/obidos/redirect?tag=your-assoc-tag%26creative=78997987%26camp=2025%26link_code=xm2%26path=ASIN/B000059HAP">
...
                </Details>
            </ProductInfo>
        </namesp1:KeywordSearchRequestResponse>
    </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

How much simpler would it be if you could skip all that? What if you could simply call a URL and get the information you need? That's how REST works. For example, you could put together the URL:

http://webservices.amazon.com/onca/xml?Service=AWSECommerceService&SubscriptionId=0NQJY4BXVZP3SFWWPZG2&Operation=ItemSearch&SearchIndex=Books&Keywords=xml

This URL is the target for a REST request. It includes various parameters the service itself needs, such as the Service, SubscriptionId, Operation and Keywords. Making a simple HTTP GET request (as you'd do by calling it up in your browser) returns a set of data:

<?xml version="1.0" encoding="UTF-8"?>
<ItemSearchResponse xmlns="http://webservices.amazon.com/AWSECommerceService/2004-10-19">
   <OperationRequest>
      <HTTPHeaders>
         <Header Name="UserAgent" 
           Value="Mozilla/5.0 (Windows; U; Windows NT 5.0; rv:1.7.3) Gecko/20041001 Firefox/0.10.1">
         </Header>

      </HTTPHeaders>
      <RequestId>18ERWMXPZQFWJSBTTP7R</RequestId>
      <Arguments>
         <Argument Name="Service" Value="AWSECommerceService"></Argument>
         <Argument Name="SearchIndex" Value="Books"></Argument>

         <Argument Name="SubscriptionId" Value="0NQJY4BXVZP3SFWWPZG2"></Argument>
         <Argument Name="Keywords" Value="xml"></Argument>
         <Argument Name="Operation" Value="ItemSearch"></Argument>
      </Arguments>
      <RequestProcessingTime>0.0858311653137207</RequestProcessingTime>

   </OperationRequest>
   <Items>
      <Request>
         <IsValid>True</IsValid>
      <ItemSearchRequest>

            <Keywords>xml</Keywords>
            <SearchIndex>Books</SearchIndex>
         </ItemSearchRequest>
      </Request>
      <TotalResults>733</TotalResults>

      <TotalPages>74</TotalPages>
      <Item>
         <ASIN>0321130073</ASIN>
         <DetailPageURL>
            http://www.amazon.com/gp/redirect.html?tag=ws&location=/exec/obidos/ASIN/0321130073%3FSubscriptionId=0NQJY4BXVZP3SFWWPZG2
         </DetailPageURL>

         <ItemAttributes>
            <Author>Elizabeth Castro</Author>
            <ProductGroup>Book</ProductGroup>
            <Title>HTML for the World Wide Web with XHTML and CSS: Visual QuickStart Guide, Fifth Edition</Title>

         </ItemAttributes>
      </Item>
      <Item>
         <ASIN>0131428985</ASIN>
         <DetailPageURL>http://www.amazon.com/gp/redirect.html?tag=ws&location=/exec/obidos/ASIN/0131428985%3FSubscriptionId=0NQJY4BXVZP3SFWWPZG2</DetailPageURL>

         <ItemAttributes>
            <Author>Thomas Erl</Author>
            <ProductGroup>Book</ProductGroup>
            <Title>Service-Oriented Architecture : A Field Guide to Integrating XML and Web Services</Title>

         </ItemAttributes>
      </Item>
...
   </Items>
</ItemSearchResponse>

That's it. No muss, no fuss, just make a GET request and get back a result.

I should point out, however, that that's not quite the end of the story. Web services do more than just request information; they also enable you to perform operations. For example, you might have a web service that ships a product or changes data in a database. These are operations with "side effects," which means that making the request causes something to happen. (Something other than simply retrieving data, that is.) You wouldn't want them bookmarked, because every time the user pulls up the bookmark, the "side effect" would happen.

The trouble with all this is that HTTP GET requests are not supposed to be used for operations with side effects. That means that while REST should remain a weapon in your web services arsenal, it can't be your only tool. You'll still need to use more "traditional" web services in some cases. But still, REST is gaining a foothold for those situations in which it's appropriate, so don't ignore it.