Standard methods for documenting a RESTful API [closed]

Answer 1

In Roy's post here he states

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).

Answer 2

Initially, we went for static documentation of resources but just had to field too many questions. Eventually, we moved to using Live documentation pages using IO/Docs (actually a fork). Been working great.

Answer 3

At my company, we've been very happy using WADL, Web Application Description Language. Wikipedia describes it as: "an XML-based file format that provides a machine-readable description of HTTP-based web applications". I find raw WADL easy to write, read, and understand, and it maps directly to RESTful concepts. The official project provides a simple spec, XSD and RELAX NG schemata, and Java tools.

A number of tools and resources exist for working with WADL, including:

• wadl_stylesheets, XSLT stylesheets to create HTML documentation from WADL files
• Restlet, a Java framework for building RESTful servers and clients, includes a WADL extension

A tip: try including human-readable documentation, such as descriptions, concepts, getting started, usage tips, etc, in the WADL document's doc element by including HTML elements, using the XHTML namespace. It can make a big difference!

Answer 4

A good ReST documentation would mean documenting your media type and only your media type.

In a typical scenario, you'd produce a document like so:

The Acme Corp XML formats

Link Discovery

Links to various resources are described in a document that can be found by issuing a GET or HEAD request to the server on a bookmark URI (typically the root of the server, http://www.acme.org), and looking for an HTTP Link header:

Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml

where the rel part is the link relationship, and the xxx is the URI for which the relationship has been established.

Link Relationships

This document defines the following relationship names:

• http://rel.acme.org/services The link relationship describes the list of links that can be navigated.
• http://rel.acme.org/customers The link for which this relationship is used is the list of customers.

Media Types

The application/vnd.acme.services+xml is a document with an xml serialization that describes a list of links an application may want to process.

<links>
 <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

The applcation/vnd.acme.customers+xml is a document with an xml serialization that describes customers.

Example documents:

<customers>
 <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

etc...

The point is to give a way to the developer to follow the links you define. First find the link to the index so they can get the list of things they can navigate to.

Once they discover that document, they discover that they can see a list of customers at a certain Uri, and can do a GET against it.

If they find a customer of interest, they can follow the link defined in /customers/customer/@href and issue a GET to retrieve a representation of that customer.

From there, your media type could embed actions that are available to the user, using more links. You also have the additional option of issuing an OPTIONS request on the resource to know if you can allow deleting the resource, or a PUT if you can save the document back after modification.

So a good documentation doesn't ever:

• give static links
• give interaction such as "you can issue POST on Customer with this media type and that will mean the move operation". The client should issue a POST against Customer only because your XML document has specified it that way.

The point of all this is to achieve minimum coupling between clients and servers. The client can be very smart in displaying and discovering resources (showing forms and god knows what else), but is totally dumb as to what the actual workflow is: the server decides.

Answer 5

You might find rest-tool useful.

It follows a language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs. It also provides a cook-book however it is in a very early stage, but its content is continuously growing.

The services you just described can be immediately used, so it is also good for experimenting.

Answer 6

I've been using http://apiary.io, which is pretty nice. You can also export the API documentation to github.