RESTful API Documentation

I'm going to design a RESTful API soon, thus I need to describe it in order to enable other people to start implementing clients using it.

I've looked around a bit, but unfortunately, I've not found any standardized form of describing web-based RESTful services. What I'am looking for is something like JavaDoc, although it don't have to be generated out of any sort of code. I'm also not talking about something like WADL, I rather want to have some human-readable documentation I can hand out.

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?

Thanks in advance & Greets

> 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 the client using an alias, this allows the entire URL structure of your site to be completely changeable without impacting the client. This makes all of the endless "what is the best way to structure my hierarchical URL" questions pretty much irrelevant. You can try it one way, and if it doesn't work, just change it, you won't break any client code or have to change any documentation!

Dynamic distribution

It is not just the path part of the URI that you can change. You could also change the host. Imagine that your app is starting to get a lot more usage than you expected, you can easily change the host of all image or video resources to point to a different server. You could even provide simple load balancing by returning different hosts. As RESTful APIs are stateless, it really does not matter which server responds to the request. This feature is useful for so many scenarios: moving HTTPS stuff onto a dedicated server, geographically distributing requests based on client location, vertically partitioning functions of the application onto different servers.

Explicit protocol

Just because a representation may return a link, does not mean that it always will. The server can only return the links that are allowed based on the current resource state. This can be really helpful when there is a specific protocol that needs to be followed when interacting with a server resource. The client code does not need to understand the rules of the protocol, it can just present to the user the links that have been made available by the server.

You can't autogen the interesting stuff

The reason why most automated efforts to document REST services are not effective is because the uniform interface removes the need to document the easy stuff. Once you understand HTTP (see RFC2616) you understand all of the mechanics of the API. All that is left is the really interesting domain specific information that cannot be generated.

Look on the bright side, the documentation should be much shorter. Any extra available time should be spent on providing examples of how to navigate the API for common scenarios.

There's no standard, just an open debate. There's an interesting article at InfoQ: Describing RESTful Applications.

If you use something like JAX-RS you can use the actual JavaDoc of the implementation as your reference. Or doing annotation scanning and generating it automatically shouldn't be too hard also, though I don't know of a specific implementation.

If you're using the MVC pattern, the URL is usually represented as:

> example.com/class/function/ID

These are pragmatic accessible pieces of information, meaning that you could still use JavaDoc and be able to document the RESTful approach, since each part of the URL is connected to the source code itself.