Agenda

• Overview of REST
• REST Example: Amazon Storage Service
• Readings for Next Time

REST

• REST stands for Representational State Transfer
• It is a software architectural style for distributed hypermedia systems, such as the World Wide Web
• The term comes from Roy Fielding's PhD dissertation from the University of California, Irvine. (As I mentioned earlier this semester, Roy and I went to UCI at the same time. I sat across the hallway from him while he was busy working on HTTP, URL, Apache, and ultimately REST.)
• Credit where Credit is Due: The next couple of slides are HEAVILY influenced by Wikipedia's article on REST

REST Design Principles

1. Stateless Client/Server Protocol: Each message contains all the information needed by a receiver to understand and/or process it. This constraint attempts to “keep things simple” and avoid needless complexity.
2. A set of uniquely addressable resources enabled by a universal syntax for resource identification; “Everything is a Resource” in a RESTful system
3. A set of well-defined operations that can be applied to all resources; In the context of HTTP, the primary methods are POST, GET, PUT, and DELETE, similar (but not exactly) to the database world's notion of CRUD (Create, Read, Update, Delete).
4. The use of hypermedia both for application information and state transitions. Resources are typically stored in a structured data format that supports hypermedia links, such as HTML or XML

• It is important to note that while the Web is ONE embodiment of these principles, it is not the ONLY one. You can create RESTful systems using other protocols, methods, resources, etc. but those new entities must conform with these design principles

REST Operations

• If we assume the standard four operations from HTTP/1.1 then the “meanings” of these operations would be something like:

• Definition of Idempotent: “Mathematics adjective denoting an element of a set that is unchanged in value when multiplied or otherwise operated on by itself.”
• From the HTTP/1.1 Spec: “Methods can also have the property of "idempotence" in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request. The methods GET, HEAD, PUT and DELETE share this property. Also, the methods OPTIONS and TRACE SHOULD NOT have side effects, and so are inherently idempotent.”
• The concept of a method being idempotent is again one of simplicity. An identical request on an idempotent method causes at most one state change in the receiving system no matter how many times it is invoked.
• Note: There are no methods for resource discovery such as LIST or FIND. Instead, collections and search results are treated as another type of resource with their own unique URLs
• Note: different people interpret these methods in different ways, with the greatest confusion centering on POST and PUT. The HTTP/1.1 spec says that POST's URI should point to a script whereas PUT's URI should point to the resource in question. That's nice BUT Apache, for instance, doesn't handle the PUT method and requires that you write a script to handle PUT requests! Furthermore, I've seen instances on mailing lists and Web forums where people insist that POST is only used for Create and PUT is only used for Update, but in practice I've seen them both used for both purposes. For instance, Amazon's S3 service uses PUT to create objects in buckets: PUT the Object in the BUCKET.

REST vs. RPC

• It is useful to consider the difference between REST and RPC, since RPC is the starting point for the middleware systems that we examined at the beginning of the semester
• In RPC systems, the design emphasis is on verbs. What operations can I invoke on the system?
  • getUser()
  • addUser()
  • removeUser()
  • updateUser()
  • getLocation()
  • addLocation()
  • removeLocation()
  • updateLocation()
  • listUsers()
  • listLocations()
  • findLocation()
  • findUser()
• In REST systems, the design emphasis is on nouns, i.e., resources and what their representation is and how they are affected by the standard set of methods
  • User
  • Location
• Thus, you would develop an XML representation for User and Location and then clients and servers would operate on these documents to exchange information via the standard set of methods.
• For example (from Wikipedia):

<user>
    <name>Jane User</name>
    <gender>female</gender>
    <location href="http://www.example.org/locations/us/ny/new_york_city">
        New York City, NY, US</location>
</user>
            

• This document is the representation used for the User resource. If clients need information about this user, then they GET this resource and process the XML document. If they need to change the information, they GET the resource, modify it, and then PUT it back on the server. Note how the reference to the Location resource includes a URI. This is an example of this document format enabling hypermedia traversal. A client could first GET this resource, see the location URI, and then “traverse” to that resource by invoking a GET on it.

Amazon S3 REST-based API

• Working with Amazon's S3 service is quite painless!
• The first step is to sign up for an Amazon Web Services Account
• The second step is to login and receive your access key and secret access key
• The third step is to download a client library (I choose the Ruby library) and try out the examples
• The fourth step is to start coding your own example.
• Amazon makes available a document that shows examples of S3's REST-based API.
• I will now give a quick demo of the Ruby API and demonstrate that I was successful in creating my own bucket and uploading a publicly accessible object into it.

Readings for Next Time

• Wikipedia REST article
• Web Services at a Crossroads
• Tim Bray, part one
• Tim Bray, part two
• Routing around the WS-* vendor stacks
• WS-* vs the REST
• unREST over WS-* and other "enterprisey" things

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 (frowned upon) or in teams of two to four students