Does REST need a service description language?

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

• A browser understands HTML enough so that it knows that it can GET the URI given by <a href>; that it is expected to (but may choose not to) GET the URI described by <img src>; and that it can either GET or POST to the URI given by <form action>, with the HTML spec describing how to use the rest of the elements inside the <form> to either augment the URI or construct a POST body.

• The Atom Publishing Protocol is mainly a description of a media type called a service document. The description explains where the client will find URIs in the service document and what kind of things can be done with a URI depending on which place in the document it was found.

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.