The Lurker

REST: there is more than one contract

I've been trying to put my finger on what it is that bugs me so much about Mark Baker's response to Patrick Mueller's question about REST:

I think you're still missing the point, Patrick.

In RESTful systems, all services expose the same contract. That's *by definition*. What is the contract? HTTP.

So when anybody asks "show me a contract for your service", just point them to RFC 2616.

I realised it reminded me of a scene from The Pitch, the episode of Seinfeld in which Jerry and George attempt to sell their show to NBC. (Scroll down to "NBC president's office".)

Aristotle Pagaltzis plays the part of Jerry, explaining what "hypermedia as the engine of application state" means in practical terms, while Mark Baker is George, counterproductively insisting that "it's a show about nothing!" the only contract in REST is HTTP, which is not only glib and condescending, but a complete failure to engage his audience – someone who wants to know how REST handles what WSDL aims to achieve. This is not effective advocacy.

In fact, you could say he's just plain wrong: he's addressing the transfer in "Representational State Transfer", and entirely neglecting the representation. As Aristotle Pagaltzis wrote:

There is a sort of equivalent to a description of an RPC API for REST, but it looks very different from what those who are looking for one would expect:

It's the media type specification.

The key to REST lies in the fact that the client understands the representations the server returns, and can interpret them to find out which other resources the server has on offer and what they can be used for.

This is a much better answer to Patrick Mueller's question – and not only was it written before Mark Baker confused matters with his "all services expose the same interface" post, it was the very post Baker was replying to. The client's ability to understand the representation implies a contract beyond HTTP.

Related topics: Rants Web Mindless Link Propagation