Does REST need a service description language?

Sunday, 27 May 2007

The other day, someone posted on rest-discuss to ask whether there was a standard way to describe a REST service. This question resurfaces from time to time (and usually draws a pointer to the WADL effort as a response), which seems to indicate a popular misunderstanding of REST.

I think describing a RESTful service with a WSDL-like language is a contradiction in terms. Consider the two defining properties of a RESTful application:

  1. Server state is exposed as a set of resources that have a uniform interface and are named by URIs.
  2. The client doesn’t make any assumptions about the server URI space; all it does is follow links.

The consequence of the first property is that there isn’t much to describe; there aren’t any methods or signatures thereof to document, since access to resources is uniform and governed by the verbs defined in RFC 2616 (in the case of HTTP, anyway). And the consequence of the second property is that what is there (the set of available resources and the verbs each of them responds to) shouldn’t be baked into the client. This second property is rarely understood – most people only get as far as the first, which explains why it is popular to think of REST as a form of CRUD.

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. F.ex.:

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. (By way of example, <cart href> and <item href> may point to resources that mean different things, even though they might respond to the same verbs – if you can PUT and/or POST to them, the request body will probably have to be constructed differently depending on the type of link. The client needs to understand these differences to successfully operate the service.)

You will notice that such a description doesn’t tell the client anything about what the URIs will look like – and that’s perfectly intentional.