Wednesday, June 6, 2007

D'oh! REST already had contracts.

The contracts and protocol exist solely in the data. A client that understand a media type can then navigate the web of links based on knowledge gleaned from documents conforming to that media type. (This is exactly hypermedia as engine of application state).

First, Joe Gregorio's excellent post mentioning OpenSearch and offering advice on balancing 1 vs. n media types.

Second, Alan Dean posting this RDF shopping example.

Notice this paragraph in the shopping example:
To validate that the server supports the "Shop" protocol, the User Agent can test the document for the existence of the basket element, e.g. with the following XPath expression count(//shop:Basket)!=0

The shopping protocol is checked with a data expression!
The shopping protocol is checked with a data expression!

My trivial example is just an instance of using data for protocol. I still think there is value in using signposts as a metaphor for self-descriptive data; if only to help people lead from programming API to hypermedia.


Aristotle Pagaltzis said...

In comments at Joe Gregorio’s, you wrote:

Let’s change the conversation from “REST doesn’t need an IDL” to the more positive “REST already has contracts, and here's how…”

Notice that my seminal post that kicked off the discussion already said that:

So this is how you describe a REST service: you explain the type of response body your server will send, where to find links in it, and what sort of semantics and verbs a particular link implies about the resource it points to.

Needless to say, I agree with you. :-)

John Heintz said...


Yes, that is exactly what you said, but a lot of people didn't hear it.

I didn't mean to imply you didn't understand this, just that the language all of these discussions are using isn't clear - especially for people coming from a codegen and IDL background.

What you quoted from your post is just as easily interpreted as IDL. Doesn't where to find links sounds exactly like the resource definitions in WADL? It sure does to Java and .NET framework enterprise developers.

A stronger, more active tone of speech will make this more clear: REST relies on shared data-based protocol contracts.

That is a stronger statement. From there we can talk about hypermedia discovery, extensible data formats that can compose many contract together (RDF, micro-formats), and how to evolve support over time.