First stops

My REST Links
More complete reading list over a longer period of time

Roy Fielding Dissertation

rest-discuss Yahoo group
very high S/N, most REST notables hang there

RestWiki (down/outdated?)


How I Explained REST to My Wife

SE Radio Podcast #98 on REST
Great intro to REST interview with Stefan Tilkov

A Brief Introduction to REST
Includes five principles:
* Give every "thing" an ID
* Link things together
* Use standard methods
* Resources with multiple representations
* Communicate statelessly

Introduction to REST (Part 1 and Part 2)
Bill Burke (from JBoss) gives intro from SOA and distributed systems point of view.

REST in less than 30 words
REST components perform actions on a resource [1] by using a representation [2] to capture the current or intended state of that resource and transferring that representation between components.

Notable people

(not in any order, probably with unintentional gaps)

Roy Fielding
Stefan Tilkov
Subbu Allamaraju (Yahoo)
Mark Baker
Bill de hÓra
Steve Vinoski
Aristotle Pagaltzis
Mark Nottingham
Stu Charton
Leonard Richardson
Sam Ruby
Joe Gregorio


JSR 311 (JAX-RS)




A Comparison of JAX-RS Implementations

Atom Publishing Protocol

* Lots of arguments for/against
* Lightweight, no libraries or skeletons required * Allows discovery of APIs in addition to specification * Use if you really want to generate stubs (but do you?)

Firefox addon: Poster
A developer tool for interacting with web services and other web resources that lets you make HTTP requests, set the entity body, and content type. This allows you to interact with web services and inspect the results.


REST, I just want it

To sum: RESTful principles are for the most part an expression, in a distributed space, of a lot of time worn wisdom about how to make good software systems that are reusable:
* minimize complexity
* maximize discoverability
* minimize exposure of special knowledge and methods
* maximize opportunities for reuse and chaining

A RESTful web service, an example

Accidentally RESTful

Steve Vinoski QCon London 2008

  ~15 minutes in: 
     Type System Illusions
       - RPC-oriented systems offer the illusion of type safety
       - But there is no type safety across the wire
       - This type specialization is costly for scalability and reuse

     Interfaces are Protocols
       - consumers hard-code knowledge of method names and
       - consumers must inherently know which method to call,
         possibly in what order
       - no semantic constraints on methods

     Data specialization
       - Using XML is better than using IDL types or programming
         language types
         - but benefits disappear if you generate code from it
           --> you cannot 'subset' an object or struct, as you
               can with XPath and similar tools
  ~22.5 minutes in:
     UNIX pipes
       - Pipe based on:
         - uniform interface of the 'file-like object'
         - standard FD framework for apps: STDIN/OUT/ERR

Serendipitous Reuse
Some responses:

QCon SF 2008 Track (RESTful web integration in practice)
Includes slides from:
- Mark Nottingham
- Ian Robinson
- Steve Vinoski
- Leonard Richardson
- Stu Charlton

Ganesh Prasad: Paying the RESTafarians Back in Their Own Coin
- Defending SOAP, routing, security, addressing, etc. by comparing to TCP/IP

Debate: Does REST Need a Description Language?

JSR 311 Final: Java API for RESTful Web Services
On some features still lacking -- support for HATEOAS.

When the JSR was initiated, there were some doubts in the REST
community about its chance of complying with REST’s key
principles. Marc thinks this goal has been met:

    I think the API encourages a resource-centric view and makes
    developers think about the identifiers of their resources and
    the methods they support. Declarative support for content
    negotiation works well and the default resource life-cycle
    encourages a stateless approach. If I had to identify a
    weakness it would have to be limited support for hypermedia
    as the engine of state - whilst we provide good support for
    extracting information from request URIs and building URIs to
    resources, its still very much left to the developer to use
    hypermedia in representations appropriately.

Paul agreed:

    Yes, this is probably the hardest area. JAX-RS provides a
    bunch of ways to construct URIs but there is no such URI
    binding facility with a modeling API, such as JAXB. I think
    there are some aspects we can explore in this respect, for
    example Henry Story’s RDF serialization.

On Linking - Part 1
Goes more into what HATEOAS means and how earlier REST APIs have evolved to take advantage of HTTP as an application protocol vs a simple transport protocol.

Craig McClanahan on HATEOAS lessons when implementing Sun Cloud API. (potentially more discussion) </p>

rest-discuss thread: "This is REST"
Discusses lack of data-oriented clients that implement HATEOAS; RTF in the thread clarifies the concept of a client 'workspace' that holds the available transitions.
Also notable for a description of a mythical 'REST tank API' by Craig McClanahan.

Snowflake APIs

Understanding hypermedia as the engine of application state

Breaks down the activities an interface typically describes:

and then which different parts of a REST interface will take care of, as well as a comparison to typical WS architecture.

This describes a richer (wrt business logic and orchestration) client than most may be used to, but one of the underlying arguments seems to be that we move toward that anyway.

Describing RESTful Applications

Example of the most common type of REST API today (using a bank + account + transfer), and pointing out where it's not RESTful and how to make it so. Discussess commonly accepted definitions of describing a REST application and how they wind up violating REST constraints.

Implementation-wise, of particular note are the returned 'link' elements and how you might specify a 'rel' ('relationship') using resource definitions. (I think Atom does this too, don't know enough about it.)

Also in slide form, plus some other intro stuff: Pragmatic REST

RESTify DayTrader

Let's RESTify DayTrader:

    DayTrader is benchmark application built around the
    paradigm of an online stock trading system. Originally
    developed by IBM as the Trade Performance Benchmark
    Sample, DayTrader was donated to the Apache Geronimo
    community in 2005. The application allows users to login,
    view their portfolio, lookup stock quotes, and buy or
    sell stock shares.

Why build a RESTful web service for DayTrader? Because I
frequently hear that REST can't be applied to complex
situations. I also want to use the example as motivation for
talking about some of the idioms that are available to handle
more extensive requirements.

Joe also wrote a series of articles on on HTTP, REST, and Atom.

REST APIs must be hypertext-driven

Roy Fielding on SocialSite API, including the memorable quote:

Today's example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

Ted Neward responds to a late-2008 brouhaha on the SocialSite API not being RESTful, and does a good job of detailing what some constraints of REST are and why they're important.

Separating REST Facts from Fallacies
Great presentation on what REST is and isn't.

What is statelessness in REST?

The road to Real REST APIs
Top of a set of exploratory articles about REST APIs, and how they interact with clients.

Thoughtworks: Podcast 4 on REST (part 1, part 2)
A little confusing because of the number of speakers, but useful because of the very high level of expertise, and the fact that they're not all either experts or REST supporters.

Fallacies of Distributed Computing Explained (PDF)

Note on Distributed Computing
1994 paper that's quoted by nearly every paper on the subject.

Another Note on Distributed Computing
Disagreeing with quite a bit on the 1994 paper.