Programming Web Services with Perl

This is the Title of the Book, eMatter Edition

Copyright © 2007 O’Reilly & Associates, Inc. All rights reserved.

248

|

Chapter 11: REST: Representational State Transfer

• Submit a purchase order

• Update or cancel a purchase order

O’Reilly also wants to enable their authors to:

• Add and update author biographical information

For internal purposes, O’Reilly also wants to enable their editors and designers to:

• Create or update a cover for the book

The next step is to consider how these services can be implemented in a REST style.

Modeling Resources

Before you can model resources, you must create a domain model, which describes

entities and their relationships and provides the information necessary for resource

modelling (see Figure 11-2).

Based on this domain model, it is possible to model the resources and design URIs to

access them. The web service makes available a specific URL to represent a books list

resource, for example, /books/.

The absolute URL for this resource may look like http://www.oreilly.com/books/, but

because the hostname and protocol will not change, there is no need to include them

in the examples.

Note that the process the web service uses to generate the response is completely

transparent to the client. A list of books may be available as a physical document or

may be created by the server side application at run-time. All the client has to do is

submit a request, and a document containing the book list is returned.

Figure 11-2. Book service domain model

CoverPage

-Book

-Color

-Subheader

-Animal

-Intro

-Title

Book

-Title

-Authors

-ISBN

-ListPrice

-CoverPage

Author

-Name

-Bio

-Books

-Articles

Article

Order

0..1

1

1..*

0..*

0..*

1..*

0..*

This is the Title of the Book, eMatter Edition

Copyright © 2007 O’Reilly & Associates, Inc. All rights reserved.

Programming REST

|

249

The XML document that a client receives may look like this:

<?xml version="1.0"?>

<Books xmlns="http://schema.oreilly.com/book"

xmlns:xlink="http://www.w3.org/1999/xlink">

<Book id="progwebsoap" xlink:href="progwebsoap/">

<Title>Programming Web Services with SOAP</Title>

<Authors xlink:href="progwebsoap/authors/"/>

<ISBN>0596000952</ISBN>

<ListPrice>34.95</ListPrice>

</Book>

<Book id="progxmlrpc" xlink:href="progxmlrpc/">

<Title>Programming Web Services with XML-RPC</Title>

<Authors xlink:href="progxmlrpc/authors/"/>

<ISBN>0596001193</ISBN>

<ListPrice>34.95</ListPrice>

</Book>

</Books>

There are several important things to notice. XML is only one of the possible repre-

sentations that a client may receive as a result of content negotiation (which will be

discussed later). The example also includes

xlink:href attributes that point to the

resources that contain related information (book and author details in this case).

This is a key feature of REST. A client changes its state by accessing the alternative

resources addressed by URLs in response document.

An xlink:href attribute is described in XLink specification that defines

an attribute-based syntax for attaching links to XML documents. The

most current version of the XLink specification can be found at http://

www.w3.org/TR/xlink/.

Note that, even though the server can make these URLs absolute (/books/progweb-

soap/ or even http://www.oreilly.com/books/progwebsoap/), for now it is kept relative.

The benefit of doing this will be clearer when discussing the “cover page” service.

The model can use the ISBN (as Amazon does, for example) instead of using unique

book identifier (as O’Reilly does), but it wouldn’t change anything in this design and

implementation.

It is important to decide what information to include in this representation and what

to keep for subsequent requests. It was decided to present

Title, ISBN, and ListPrice

elements and provide links to other resources. While it is possible to include all rele-

vant information, it’s not always feasible or practical. For example, book informa-

tion may include a cover page; author information may include the author’s bio and

pictures as well as links to articles. There is no reason to include all this information

in the book list, so the line must be drawn somewhere.

At this stage, the server has implemented a service that returns a list of books. Work

can now focus on the service that returns specific information about a particular

book. This service will be available through the URL /books/progwebsoap/.