Lecture 16: REST Example

Agenda

REST Example: Address Book
Discussion of Readings
Information on Class Project

REST Example: Address Book

I have constructed a small address book application (actually more like an LDAP directory service) using the REST architectural style
This application has one main resource, MEMBER, and a pseudo-resource, GROUP. The Member resource is a small XML document that has three elements (name, phone, email). The Group resource does not quite match the RESTful definition because while it maps to unique URLs, it actually has TWO XML files that contribute to its “state”. These XML files are updated as part of the initial state change associated with PUT and DELETE methods on Groups and Users.
The server-side of the application is implemented as two cgi scripts hosted by an instance of the Apache Web server
The front-end of the application is a set of command-line scripts that allow groups and members to be created, deleted, listed, etc.
- I chose to implement the front-end as a set of command-line scripts to emphasize that the REST architectural style can be realized in many different ways; I could, if I want, construct a Web-based front end for the system to allow users to access this information via a Web browser
- Indeed, I will end this example with showing how XML documents can make use of CSS stylesheets to specify how they should be presented in Web browsers. Such a mechanism allows a Web server's/browser's default behavior for the GET method to be used to browse information in a RESTful system.

Step One: Configure Web Server

In order to create a REST-based application, you need a Web server that supports the use of the PUT and DELETE methods. (Most Web servers support only GET and POST by default).
After a long session of trial and error, I eventually configured Apache on my laptop to support these methods. The basic procedure was:
- Identify a directory where the REST-based application would “live”
- Enable the use of PUT and DELETE in that portion of the directory tree by mapping these operations to a cgi script
- Configure Apache to allow cgi scripts to be written in the Ruby scripting language
- Enable CGI script execution in the directory where the cgi scripts were stored
Here are the relevant details from my /etc/httpd/users/kena.conf file:

AddHandler cgi-script rb

<Directory "/Users/kena/Sites/cgi-bin">
    Options +ExecCGI
</Directory>

<Directory "/Users/kena/Sites/addressBook/data">
    Options +ExecCGI
    Script PUT /~kena/cgi-bin/put.rb
    Script DELETE /~kena/cgi-bin/delete.rb
    AllowOverride All
    <Limit GET POST PUT DELETE OPTIONS PROPFIND>
        Order allow,deny
        Allow from all
    </Limit>
    <LimitExcept GET POST PUT DELETE OPTIONS PROPFIND>
        Order deny,allow
        Deny from all
    </LimitExcept>
</Directory>

Step Two: Write CGI Scripts

I had to write two scripts, one to handle PUT requests and one to handle DELETE requests
In both cases, the key piece of information for both scripts was the contents of the PATH_TRANSLATED environment variable. This environment variable maps the request URI into a location on the local file system.
- Thus a URL like <http://localhost/~kena/addressBook/data/CU/0.xml> is translated into </Users/kena/Sites/addressBook/data/CU/0.xml> by the Web server and placed in the PATH_TRANSLATED environment variable.
Here are links to the two scripts that I developed:
put.rb delete.rb
These scripts determine whether the path they have been asked to process contains the pattern “.xml”; If so, they process the URI as a Member, otherwise as a Group. Semantics of the various operations are shown below:

	GET	PUT	DELETE	POST
Groups	command line tools either append groups.xml or members.xml to request based on the purpose of the GET; Apache handles this request	creates a new group; updates the groups.xml file of the parent group	removes the specified group; updates the groups.xml file of the parent group	not used
Members	retrieves the member's XML file; Apache handles this request	creates a new member; updates the members.xml file of the specified group	removes the specified member; updates the members.xml file of the specified group	not used

Step 3: Write the command line scripts

I wrote the following command line scripts for this application:

Command Name	Example	Explanation
createGroup	createGroup CU/CS	Creates a group CS within the group CU
removeGroup	removeGroup CU/CS	Remove the group CS from the group CU
listGroups	listGroups CU	List the groups contained within the group CU; invoke command with no arguments to see top-level groups
addMember	addMember CU	Add a new member to the CU group; the addMember script asks you a series of questions to create the new member
removeMember	removeMember CU Ken Anderson	Remove the member Ken Anderson from the group CU
listMembers	listMembers CU	Retrieve the member names of the group CU
numMembers	numMembers CU	Print the number of members of the group CU
getMemberInfo	getMemberInfo CU Ken Anderson	Retrieve the XML file for Ken Anderson who is a member of the group CU and pretty print its information
getMemberIds	getMemberIds CU	For the group CU, map member names into member ids that can be used to construct the URI of a member resource

Discussion

In what ways does this application follow the REST architectural style?
In what ways does it not follow the REST style?
What simple changes could we apply to make this application more RESTful?

Address Book, Take 2

Since I was unhappy with the initial approach that I took with creating a RESTful address book example, I started sketching the implementation of a second approach last night.
Key Differences:
- Implementation is Incomplete: only createGroup, listGroups, listMember, and listMembers implemented
- Hierarchy is gone, BUT
- Switch to using uniform URLs and file names
  - Collections: groups/index.xml and members.xml
  - Individual Group : groups/1/index.xml
  - Individual Member: members/1/index.xml
Much cleaner design (in my opinion)

Discussion of the Readings

Below I summarize some key points from the reading list; lets take some time to discuss them and explore any questions you may have about these articles
Wikipedia REST article: Already discussed (unless someone has a disagreement or additional point to raise)
Web Services at a Crossroads: sees Web services as distinct from middleware, which is a different perspective than the one presented in our textbook; also, use the right tool for your job, don't shoehorn your problem into an inappropriate technology solution
Tim Bray, part one: Starts with Don Box saying “do both”, goes to an advocate for WS-*, and then slides heavily to REST supporters
Tim Bray, part two: Again starts with Don Box showing how Microsoft has supported REST, goes over to Tim who says that WS-* isn't very Web-like, back to Don Box who talks about issues of Hi-Rest and Lo-Rest, and then moves into a discussion about the two types of Web (one for people and one for machines)
Routing around the WS-* vendor stacks: An opinion piece that WS-* is “another ivory tower where no sane person wants to live!”
WS-* vs the REST: Interesting article where it is revealed that the lion share of developers using Amazon's web services make use of the REST-based API

Need Volunteers!

Discussion of Fielding's Thesis, chapter 5 and chapter 6 AND/OR Fielding's Paper on REST
Discussion of Creating a REST Protocol
Discussion of the Atom Publishing Protocol. This article on XML.com may help: Catching up with the Atom Publishing Protocol
Other presentations on REST-based Web Services, such as NewsGator's APIs.

Class Project

Create a non-trivial Web Service using either the WS-* approach or the REST approach
- At least some of the services should be accessible by a user using a Web browser (to monitor status, for example)
- If your service is not entirely Web-based, then be sure to implement a client application that makes use of the service in some way
Create a 10-20 page report that
- Presents a review of the concepts discussed in the class
- A description of the purpose of your Web service
- A description of the design of your Web service along with an architecture diagram
- A discussion of any implementation issues that you encountered while building the service
- A short tutorial that demonstrates how to interact with your Web service
- A URL that points to an archive containing the source code of your service
- (Optional) A URL that points to a running version of your service
You may work alone or in teams of up to four students

Web Services

Lecture 16: REST Example

Agenda

REST Example: Address Book

Step One: Configure Web Server

Step Two: Write CGI Scripts

Step 3: Write the command line scripts

Discussion

Address Book, Take 2

Discussion of the Readings

Need Volunteers!

Class Project