[Reprinted] [rest] Building Web services the rest way

Building Web services the rest way
Roger L. Costello

I will first provide a brief introduction to rest and then describe how
Build Web Services in the rest style.
What is rest?
Rest is a term coined
By Roy Fielding in his Ph. D. Dissertation [1] to describe an architecture style
Of networked systems. Rest is an acronym standing for representational state
Transfer.
Why is it called representational state transfer?
The Web is
Comprised of resources. A resource is any item of interest. For example,
Boeing Aircraft Corp may define a 747 resource. Clients may access that resource
With this URL:

Http://www.boeing.com/aircraft/747

A
Representation of the resource is returned (e.g., boeing747.html).
Representation places the client application in a State. The result of
Client traversing a hyperlink in boeing747.html is another resource is accessed.
The new representation places the client application into yet another State.
Thus, the client application changes (transfers) state with each resource
Representation --> representational state transfer!

Here is Roy Fielding's explanation of the meaning of representational state
Transfer:

"Representational state transfer is intended to evke an image of how
Well-designed web application behaves: a network of web pages (a virtual
State-machine), where the user progresses through an application by selecting
Links (state transitions), resulting in the next page (representing the next
State of the Application) being transferred to the user and rendered for their
Use ."
Motivation for rest
The motivation for rest was to capture
Characteristics of the Web which made the Web successful. Subsequently these
Characteristics are being used to guide the evolution of the web.
Rest-
Invalid tural style, not a standard
Rest is not a standard. You will not see
The W3C putting out a rest specification. You will not see IBM or Microsoft or
Sun selling a rest developer's toolkit. Why? Because rest is just
Invalid tural style. You can't bottle up that style. You can only understand it,
And design your web services in that style. (analogous to the client-server
Invalid tural style. There is no client-server standard .)

While rest is not a standard, it does use standards:

HTTP
URL
XML/html/GIF/JPEG/etc (resource representations)
Text/XML,
Text/html, image/GIF, image/JPEG, etc (MIME types)
The classic rest
System
The Web is a rest system! Understanding of those Web services that you have
Been using these policyears-book-ordering services, search services, online
Dictionary services, etc-are rest-based Web Services. Alas, you have been
Using rest, building rest services and you didn't even know it.

Rest is concerned with the "big picture" of the web. It does not deal
Implementation Details (e.g., using Java servlets or CGI to implement a web
Service). So let's look at an example of creating a Web service from the rest
"Big picture" perspective.
Parts depot Web Services
Parts depot, Inc
(Fictitious company) has deployed some web services to enable its customers:

Get a list of parts
Get detailed information about a participant
Part
Submit a purchase order (PO)
Let's consider how each of these
Services are implemented in a restful fashion.
Get parts list
The Web
Service makes available a URL to a parts list resource. For example, a client
Wocould use this URL to get the parts list:

Http://www.parts-depot.com/parts

Note
That "how" the Web service generates the parts list is completely transparent
The client. All the client knows is that if he/she submits the above URL then
Document containing the list of parts is returned. Since the implementation is
Transparent to clients, parts depot is free to modify the underlying
Implementation of this resource without impacting clients. This is loose
Coupling.

Here's the document that the client has ES:

<? XML version = "1.0"?>
<P: Parts xmlns: P = "http://www.parts-depot.com"


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

<Part id = "00345" xlink: href = "http://www.parts-depot.com/parts/00345 "/
>

<Part id = "00346" xlink: href = "http://www.parts-depot.com/parts/00346 "/
>

<Part id = "00347" xlink: href = "http://www.parts-depot.com/parts/00347 "/
>

<Part id = "00348" xlink: href = "http://www.parts-depot.com/parts/00348 "/
>
</P: Parts>
[Assume
That through content negotiation the service determined that the client wants
The representation as XML (for machine-to-machine processing).] note that
Parts list has links to get detailed info about each part. This is a key feature
Of rest. The client transfers from one State to the next by examining and
Choosing from among the alternative URLs in the Response document.
Get
Detailed Part Data
The Web Service makes available a URL to each part
Resource. example, here's how a client requests part 00345:

Http://www.parts-depot.com/parts/00345

Here's
The document that the client has ES:

<? XML version = "1.0"?>
<P: Part xmlns: P = "http://www.parts-depot.com"


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

<Part-ID> 00345 </part-ID>

<Name> widget-A </Name>
<Description> This part is used
Within the FRAP Assembly </description>
<Specification
Xlink: href = "http://www.parts-depot.com/parts/00345/specification "/
>

<Unitcost currency = "USD"> 0.10 </unitcost>

<Quantity> 10 </quantity>
</P: Part>
Again observe how this
Data is linked to still more data-the specification for this part may be found
By traversing the hyperlink. Each response document allows the client to drill
Down to get more detailed information.
Submit Po
The Web Service makes
Available a URL to submit a po. The client creates a po instance document which
Conforms to the PO schema that parts depot has designed (and publicized in
WSDL document). The client submits Po. XML as the payload of an http post.

The PO service responds to the HTTP post with a URL to the submitted Po.
Thus, the client can retrieve the Po any time thereafter (to update/edit it ).
The PO has become a piece of information which is shared between the client and
The server. The shared information (PO) is given an address (URL) by the server
And is exposed as a web service.
Logical URLs versus physical URLs
A
Resource is a conceptual entity. A representation is a concrete manifestation
The resource. This URL:
Http://www.parts-depot.com/parts/00345

Is
A logical URL, not a physical URL. Thus, there doesn't need to be, for example,
A static html page for each part. In fact, if there were a million parts then
Million static html pages wocould not be a very attractive design.

[Implementation detail: parts depot cocould implement the service that gets
Detailed data about a participant part by employing a java servlet which parses
The string after the host name, uses the part number to query the parts
Database, formulate the query results as XML, and then return the XML as
Payload of the HTTP response.]

As a matter of style URLs shocould not reveal the Implementation Technique
Used. You need to be free to change your implementation without impacting
Clients or having misleading URLs.
Rest Web Services Characteristics
Here
Are the characteristics of rest:
Client-server: a pull-based interaction
Style: consuming components pull representations.
Stateless: each request
From Client to server must contain all the information necessary to understand
The request, and cannot take advantage of any stored context on
Server.
Cache: to improve network efficiency responses must be capable
Being labeled as cacheable or non-cacheable.
Uniform interface: all resources
Are accessed with a generic interface (e.g., http get, post, put,
Delete ).
Named resources-the system is comprised of resources which are
Named using a URL.
Interconnected resource representations-
Representations of the resources are interconnected using URLs, thereby enabling
A client to SS from one state to another.
Layered components-
Intermediaries, such as proxy servers, cache servers, gateways, etc, can be
Inserted between clients and resources to support performance, security,
Etc.
Principles of rest Web Service Design
1. The key to creating web
Services in a rest Network (I. e., the Web) is to identify all of the conceptual
Entities that you wish to expose as services. above we saw some examples
Resources: Parts list, detailed part data, purchase order.

2. Create a URL to each resource. The resources shoshould be nouns, not verbs.
For example, do not use this:

Http://www.parts-depot.com/parts/getPart? Id = 00345

Note
The verb, getpart. Instead, use a noun:

Http://www.parts-depot.com/parts/00345

3.
Categorize your resources according to whether clients can just receive
Representation of the resource, or whether clients can modify (add to)
Resource. For the former, make those resources accessible using an http get.
The later, make those resources accessible using http post, put, and/or delete.

4. All resources accessible via http get shocould be side-effect free. That is,
The resource shoshould just return a representation of the resource. Invoking
Resource shocould not result in modifying the resource.

5. No man/woman is an island. Likewise, no representation shocould be
Island. In other words, put hyperlinks within resource representations to enable
Clients to drill down for more information, and/or to obtain related
Information.

6. design to reveal data gradually. Don't reveal everything in a single
Response document. provide hyperlinks to obtain more details.

7. Specify the format of response data using a schema (DTD, W3C schema,
Relaxng, or schematron). For those services that require a post or put to it,
Also provide a schema to specify the format of the response.

8. Describe how your services are to be invoked using either a WSDL document,
Or simply an HTML document.
Summary
This article described rest as
Invalid tural style. In fact, it's the actual tural style of the web. Rest
Describes what makes the Web work well. Adhering to the rest principles will
Make your services work well in the context of the web.

In a future article I will write about the evolution of the Web using
Rest principles.
Acknowledgement
Thanks to Robert leftwich and Philip
Eskelin for their very helpful comments in creating this document.

References
[1]

Http://www.ebuilt.com/fielding/pubs/dissertation/top.htm