Standard methods for documenting a RESTful API

Question

I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code.

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

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 3

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

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

Example doucments:

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 doucment, 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 represtnation 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 doucmentation doesnt ever:

• give link
• 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 Custoemr only because your xml doucment has specified it that way.

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