Documenting a REST service

Question

I would like to thoroughly document an API service (with at least HTML). This service follows resource-oriented RESTful best practices. Are there any tools that can assist in compiling and and maintaining this documentation, or do I have to build it all from scratch?

Answer 1

What I do I generate both the service interface and the documentation from an XML file, by going through an XSLT transformation. The XML is something like:

<type name="User">
 <field name="Name" type="string">
 <description>The User Name</description>
 </field>
</type>
<resource name="Users" type="User">
  <verb name="Add" method="POST"/>
  <verb name="List" method="GET"/>
</resource>

From this I run one XSLT that generates the HTML documentation and one that generates the service entry point code (in this case PHP, but is irelevant). The XML format and both XSLTs are craeted by me from scratch, but the gist of this is that there is one single definition for both the spec and the code: the XML file. In fact there is a 3rd XSLT that is used to generate the REST service client code (C# in my case), from the same XML. I'm quite happy with this approach, but I reckon is a very specific solution, not some industry agreed practice.

I have asked a similar question Should I describe REST services in a machine readable format.

Answer 2

All you need to do is document your media types. To quote Roy from here

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). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

Answer 3

I have implemented multiple REST production systems and have come to the conclusion that the self-documenting aspect of REST is it's most misunderstood and dangerous part (very usable, but must be handled with care). At least don't use it as yet another excuse for not writing an initial spec (it's significantly easier to change the behavior of a program in human code than to do it after the API has been implemented).

However try to keep the documentation lean. It's really very similar to writing ordinary API documentation, where you want the classes/methods to have obvious names/responsibility and you only want to consult the documentation for non-obvious information (such as initial client state and error conditions). If you aim for a similar REST service API then you should be safe.

But do write some documentation! (fx. based on the initial spec). Most people actually do prefer a readable API rather than cycling through a WADL file or looking for wired URI pointers inside XHTML/Atom fragments.

Answer 4

I'd love to know why you thought Enunciate hard to use.