RESTful API Documentation

Due to the nature of RESTful web-based services, it should be quite easy to standardize a documentation. It should just list available ressources, corresponding URIs, allowed methods, content-types and describe the availabe actions. Do you have any suggestions therefore?

This is absolutely the wrong way to go about documenting REST services.

One URI to rule them all

You should never enumerate URIs of the resources because that would encourage a client to hard code those URIs into the client code. This creates unnecessary coupling between the client and the server. URIs should be discovered based on navigating from the services root URI. The root URI is the only URI that should be documented. The documentation should focus on describing what information and links are in the representations that are returned. If you start with the representation that is returned from the root URI, you can describe the media type and what are the links that may be provided in that document.

Alias your URIs

It is important to use some kind of alias to create a layer of indirection between the client and the server. If you follow the atom:link standard for defining links then the rel attribute becomes the identifier. However, there are other ways of defining links, like, for example, the way images are embedded in html. An image tag can have an Id and a href. The Id tag should be used to identify the image that you wish to access the URL for.

The media types define your API

The end result is that you define all the endpoints in your API within the context of some representation. The complete API is defined by the set of returned representations and the links that connect them.

So you may ask, what is the difference? Why not just create the list of endpoints? Here are a few reasons,

Changeable URI space

Because those links are accessed by th