Introduction to REST

This presentation was given at the "SOA that Talks" panel by Steve Bjorg.

Many thanks to Roger C., Aristotle P., and Ernie P. for their input.

	Presented by Steve Bjorg. CTO and co-founder of MindTouch, Inc.
	First, we'll state what is REST is. Then, we'll define by principle and by an example.
	REST is a design pattern.  It's not a technology like SOAP or HTTP.  REST is a novel way to decompose an application into smaller parts, so that the whole works better in a distributed setting.  And that's really what REST is about.  It's a proven design pattern for building loosely-coupled, highly-scalable applications.
	The benefits of abiding to the REST design pattern are multiple and important.  First, REST is incredibly simple to define.  There are just a few principles and semantics associated with it.  Next benefit is that it leads to a very scalable solution by promoting a stateless protocol and allowing state to be distributed across the web.  Finally, it leads itself well to relegate part of the load to proxies and other intermediaries.
	Now, let's define REST by principle.
	First and foremost, in REST, everything is a resource.  A resource can be thought of a distant thing that you can interact with, but not manipulate directly.  This is similar in spirit to object-oriented programming where everything is an object, but the approach is fundamentally different.
	Every resource has at least one name.  This name must be unique and can only refer to one resource.  On the web, URI/XRIs are perfect match for this requirement.  They enable a resource to be found by any application.
	Every resource is interacted with using a universally predefined set of VERBS.  These verbs are not defined by individual resources, but across all resources.  On the web, the verbs are the standard HTTP methods POST, GET, PUT, and DELETE.  Each verb has clear defined semantics that can be relied upon.  This is critical so intermediaries can do the right thing.
	Since resources can be thought of far away things, it is not possible to manipulate the resource directly.  Instead, through communication, we can exchange representations for the resource.  The representation can be intended for human interaction (e.g. a HTML page) or for machine-to-machine interaction (e.g. XML or even binary data).
	And that's really it.  All you need to do, is remember this simple diagram: Everything is a resource Every resource has a name All operations are done with simple, predefined verbs And you only ever interact with a resource through its representation
	Ok, now that we have the theory behind us.  Let's look at a concrete example.
	In this case, we'll look at a customer who wants to change his order with ACME Enterprises using web-services.
	So, the first thing our customer does is retrieve his profile from our server at http://acme.com/customers/coyote.  The profile contains the usual data like his name, but also his portrait, which is stored on his own server, and a link to where his orders are stored.  What is important to note here, is that all the related information is found by inspecting the representation.  The agent who retrieved the document does not need to have an understanding of where these resources are.  Instead, the links can be thought of as completely opaque resource name that we can interact.
	So, let's go ahead of retrieve our customer's orders.  This is another XML document that lists the 10 most recent orders that were placed.  Again, we see embedded in the resource a link that allows to go back to the customer's profile, as well as a link to retrieve the previous 10 orders.  This is a small detail, but very important. The agent who retrieved this document only needs to understand that the presence of the <next> tag indicates more results.  It does not need to know how this is encoded in the link.  Again, the link is completely opaque. Part of the orders document, is the most recent order which is shown as open.  This is the order the customer wants to change.
	Same as before, let's fetch the order.  We see that our customer ordered one ACME Rocket, but actually wanted 4.  Now, let's see how we change that.
	Let's go and change the representation we received of the order to show 4 ACME Rockets instead of one.  And now we use the PUT verb to update the resource to reflect the new state.  That's all that is needed to be done!  We retrieved the representation of the resource, we changed that parts of it we needed, and then we simply sent it back.
	So, let's review and see if this example reflects the benefits we stated that REST has. First, we can see how the interactions were very simple by taking a resource-centric view.  Also, we operated with simple, predefined verbs. Second, we saw how we can discover new resources easily through interactions.  Giving the application architect the opportunity to distribute the required state to wherever it needs to be for whatever reason.  Also, less noticeable, important to point out, the protocol to interact with the resources is completely stateless.  We could have directly updated the order if we had known the name of that resource. Last, and this is very important, we can benefit from intermediaries that might exist between the agent and the resource.  For example, it makes sense to indicate to the agent that a user profile doesn't tend to change often and can therefore be cached.  Such mechanism exists in HTTP, which leads it to a good candidate technology for implementing distributed applications.
	There is a lot more to learn about REST.  I really have only scratched the surface.  The best starting point is of course Roy Fielding's thesis where the term REST was coined and the benefits well explained. Another great example of REST applied to solving actual problems is to look at the Atom Publishing Protocol specification.  Atom is similar to RSS and the Atom Publishing Protocol adds the ability to not only read, but also create and modify entries. Another related resource, is the HTTP spec.  While the REST pattern can be applied to any environment, even in imperative programming languages, it makes sense to use in conjunction with HTTP.  After all, REST's goal is to keep distributed applications simple, make them more scalable, and allow for a layered environment.  So, it only makes sense to build on top of an already very successful distributed protocol such as HTTP. Lastly, there is a great discussion group on Yahoo! where you can post questions REST.  If nothing else, subscribe to it and learn about where things are heading.
	These slides and other REST related information can be found at our OpenGarden site.  OpenGarden is MindTouch's open-source community site.  You'll find links to the references I mentioned before.  You will also find information about our open-source REST framework for .Net and Mono, which makes it easier to create REST services on top of HTTP.

Notes for future presentations:

• focus more on WHY
• further emphasis on selecting HTTP as the transport protocol for REST services/applications
• emphasize that behind each URI there is behavior that acts upon the resource
• Feedback from Roy F.:
  • Hypermedia is the engine of application state
  • REST simplifies applications because it rips apart the million
    potential states inherent in any serious application and presents
    to the client only one at a time, with every single transition
    from that state described in a format that can be understood by
    the client as a potential transition.  The client is completely
    decoupled from the server aside from the shared agreement on what
    each media type means.  The entire application only needs to be
    understood (and can be completely tested) one state at a time.
    
    The only difference between machine-to-machine interaction and
    human-browser interaction is the choice of media types and the
    degree to which the potential transitions are described by those
    types. A browser knows the difference between an anchor and an
    in-line image because the media type standard defines that difference.
    It doesn't have to ask the user each time whether they want a
    given relationship to be treated as an in-line image, stylesheet,
    javascript, atom subscription, or any of the other relationships
    that are automated with even browser-based hypermedia.  A pure
    machine-to-machine simply automates all transitions based on
    some predefined (or adaptive) criteria that is evaluated for
    each representation received.
    
    Hypermedia means the placement of controls within the presentation
    of information -- it is not just a GUI paradigm.