Standard methods for documenting a RESTful API [cl

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

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

Answer 2

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 3

To create understanding/documentation, heavyweight solutions aren't always needed. Examples of (great) heavyweight tools are: IO/Docs / Apigee (although great tools).

For tiny projects that already have a docchain setup (doxygen/phpdoc/phpdoctor/custom/etc) I use the following shellscript to just include the page in the full generated documentation:

https://gist.github.com/4496972

A demo: http://pastie.org/5657190

It just use custom comment-tags in your sourcecode. It can also be a nice starting point for documenting any sourcecode (language).

Answer 4

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 5

Sure, REST APIs should ideally use HATEOAS and be hypertext driven (with heavy use of media types), but also having simple human-friendly documentation for developers to work off of is helpful.

Some specific tools that are helpful for generating documentation like this:

• Swagger
  • An open spec for describing REST APIs [ github ]
  • Tools for auto-generating
    • Documentation
    • Code for your API
  • Donated to the OpenAPI initiative and renamed OpenAPI in 2015
• Mashery
  • An open source project [ github ]
  • Tools for generating
    • Documentation
    • An exploration interface for your API
• Apiary and API Blueprint
  • Write the API description in a DSL within markdown
  • Tools for auto-generating
    • Documentation
    • Mock server
  • Seems to be focused on ruby+mac devs
• RAML
  • A spec for describing REST APIs [ github ]
• WADL
  • A spec for writing discoverable API docs with XML
  • Some discussion comparing WSDL and WADL
• APIgee
  • A commercial product with some documentation features
• 3scale
  • A commercial product with some documentation features
• miredot
  • Commercial REST API documentation generator
  • Java specific

Answer 6

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!