Best tool for writing REST API documentation?

Question

Hi all,

I am in the process of writing up documentation for a REST API that I have developed. I am finding this to be tedious and the current way we are doing it just doesnt seem right. I am sure there is something out there which will help automate this process a little, and even provide features such as version control for the documentation.

I am not looking for a tool which will extract out all our status codes for each service available, I am happy to manually write up things, but something which is project like (i.e. Maven?) and will allow me to use SVN or some other version control system and if it produced a PDF at the end of it, it would be a bonus..

Thanks

Answer 1

Hi,

actually, your API should not require any documentation beyond the specifications of the media types the API uses. Any other documentation would just create coupling between client and server that REST is aiming to avoid.

As an example, look at RFC 5023 (AtomPub) and RFC 4287 (Atom) which together provide the documentation needed to develop AtomPub clients.

What kind of information is it, you intend to document?

I am currently working on a series of blog posts that aim to provide a practical example of these issues, but it will take me another week or so. ( http://www.nordsc.com/blog/?cat=13 )

HTH,

Jan

Answer 2

Use a wiki ?

How RESTful your API is will determine what exactly you need to describe about it. If you aren't leveraging the hypertext constraint - i.e. your application is not driven exclusively by links and link relations - then you are going to have to describe stuff like URI patterns and specific processing rules for each type of resource in your application(s).

Answer 3

To avoid docs, which aren't read by users and are inconsistent with the application, we do following. It is less about writing lengthy word-documents, but being more close to the api-application:

• Include some decent metadata, which describes your data inline (e.g. http://.../users/metadata would give you metadata about your user-representations). This coul be links to XSD or read/write constraints)
• A live sandbox api-client, which shows you all the possible requests and offers live links, forms or curl statements including showing you the payload. Offering such a thing involves work, but makes the discovery of your api very playful and learning by example.
• Include a small HTML-tutorial directly visible inside the api-webapp context root. Work a lot with hypermedia here.

Though api is meant to be used by programs, always remember that it's the humans developing these programs.