Writing REST API documentation
Recently I had the pleasure of working on some REST API documentation. I really enjoy this, because it is quite a change from the sort of thing I usually write. It’s highly technical stuff. The developers learned a lot while developing the code, and I learned a lot from working with them on the documentation.
Updated on Tuesday 11 February 2014: I’ve updated the links in this post, added a link to a tutorial, and removed some obsolete links, to reflect changes in the Atlassian documentation.
Most of the documentation was written by our developers, in particular Sam Le Berrigaud. My job was to massage the style and structure and add bits on the periphery.
Some bloggers have commented that there’s a fair amount of information available on the web about REST principles, but not much about actual implementations. We have published our REST API design guidelines. We’ve also added a document explaining how to use our REST plugin module to create REST APIs. (Added later: a tutorial on developing a REST service plugin.]
When we release our first product that uses the REST module in the wild, I’ll be able to link to more documentation about REST implementations. That will probably be Crowd 2.0, which will provide a REST API based on the REST plugin. I’ll let you know when that happens, because then we’ll have some documentation on using the API itself.
This is exciting stuff, especially when you start getting an inkling of how neat and powerful a REST API can be. That’s why I enjoy writing about it. It’s satisfying and rewarding to write about technology that is neat and tidy.
So, the developers and I have learned a lot. But I’m sure there’s more to learn. We know that we need to add information on installing the REST plugin and its dependencies, and some examples along the lines of this forum discussion.
If you have written REST API documentation or designed and worked with REST APIs, I’d be really interested to hear your ideas, both about the API design and about the documentation itself.
There’s nothing more RESTful than a tree 😉
Here’s a picture of my Prickly Paperbark tree. How it’s grown! It is now one year nine months old, the same age as this blog. I planted the tree in August 2007 — see how small it was then.
Writing REST API documentation
Posted on 16 May 2009, in APIs, technical writing, trees and tagged Paperbark Tree, prickly paperbark, REST API, technical communication, technical documentation, technical writing. Bookmark the permalink. 17 Comments.
ffeathers 
Hi Sarah,
I’m in the process of documenting some REST APIs for the very first time, and I’m wondering if you did any sort of automation of the documentation? This seems to be a little-discussed area of REST documentation and I’m hunting for tidbits!
I’m familiar with utilities like Sandcastle for API documentation, and though there seem to be similar ones for REST, we’ve not had much luck with those.
Do you have to go back and redocument if the API changes? Or can you regenerate your documentation using some kind of automated system?
many thanks in advance!
paul
Hallo Paul
That’s a great question! When we did the documentation that I was writing about in the above post, we wrote it all by hand. This is because the documentation was mostly an explanation of the design and implementation of the REST APIs themselves, rather than a description of how to use an API after implementation.
Now we’re nearly a year down the track, and we have implemented some working APIs that developers can use to access the applications. And yes, we do use automation to create the documentation.
We’re a Java shop and we use Jersey to develop our REST APIs. The developer writes the documentation via annotated comments in the Java code.
Jersey’s WADL generator searches the source code for the annotations and adds the Javadoc as <http://research.sun.com/wadl/2006/10:doc> elements to the various elements in the WADL. It is this documentation that allows our XSL transform to produce useful HTML.
Jersey’s WADL generator supports a number of custom Javadoc tags and provides a custom doclet that reads them. The developers use these tags to document the various status codes that a REST resource can return and provide examples of actual request and response documents that a user can encounter.
There’s a list of supported annotations on the Sun wiki for Jersey. The developer then runs a procedure to build the WADL XML file, and an XSLT procedure to convert the XML to HTML.
Here’s an example of such generated documentation:
http://docs.atlassian.com/atlassian-confluence/REST/3.2/
As technical writer, I worked with the developer on the above documentation, advising him what sort of information would be useful and tweaking the grammar. It’s an interesting experience, and it’s also great to know that the documentation will be kept up to date by the automatic generation each time the API itself is updated.
Phew, I hope all that helps!
Cheers
Sarah
Sarah, How would you document a REST API created in .net for automatically generating WADL documents?
Thank you.
Hallo Anil
I don’t know all that much about documenting .NET APIs. I asked my husband, who is a .NET developer. There are 2 tools worth investigating: NDoc and Sandcastle.
Firstly, it’s worth knowing that the developers will probably be using the triple slash convention “///” to document each method etc. The comments they create in this way are used by IntelliSense (an autocomplete feature) to produce the prompts for the developer inside the IDE (Visual Studio).
Information about tags: http://msdn.microsoft.com/en-us/library/5ast78ax(VS.80).aspx )
NDoc is tool that has been around a while: http://www.codeproject.com/KB/aspnet/NDoc.aspx You can run NDoc on the source, and it will extract the same comments as produced for IntelliSense. NDoc produces Microsoft Help output. I don’t know if it produces other outputs too.
A problem with NDoc is that it does not support the latest language features. Things like “generics” in .Net are very important, so if a tool (like NDoc) does not support this feature, it’s probably worth looking at a different tool.
Another tool worth investigating is “DocProject for Sandcastle”:
http://docproject.codeplex.com/
http://docproject.codeplex.com/wikipage?title=About%20DocProject&referringTitle=Home
“Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:
* Works with or without authored comments
* Supports Generics and .NET”
Now that my husband has mentioned Sandcastle, I remember it being mentioned once at a Microsoft talk I attended. I blogged about it here: https://ffeathers.wordpress.com/2009/04/01/writersua-2009-day-1/
It seems to be very powerful and it is up to date. Evidently Sandcastle can use the “///” tags, but does a lot more as well.
Good luck, and let me know how it goes!
Cheers, Sarah
maybe you can try enunciate(http://enunciate.codehaus.org/) for automation of REST API documentation.
Hallo Ankit
Thank you for that reference. I’m busy compiling a list of API document generators, and enunciate looks very interesting indeed.
Cheers, Sarah
Hello Sarah,
My project is looking into different options on how to make API documentation for our new REST API. Your blog articles have been useful reading, and after reading the comments here, I have been looking into alternatives for generating the documentation from our source code.
We are currently using RESTEasy, and as far as I know, Enunciate still does not support this – http://jira.codehaus.org/browse/ENUNCIATE-259
Do you know about any other generators that support RESTEasy?
Many thanks in advance,
Vegard
Hallo Vegard
I’m afraid I don’t know anything about RESTEasy. I’ve asked the question on our intranet, but no response yet. I’ll let you know if anyone does reply.
If anyone reading this post at some time in the future has some feedback, I’d love to hear it too.
Cheers, Sarah
IG Group have recently open-sourced their RESTdoclet solution, which is specifically aimed at services built using Spring’s REST framework. We use this internally to automatically document all our RESTful services and publish these via an internal web portal.
More info here: http://ig-group.github.com/RESTdoclet/
Robert @ IG Group
Thanks very much, Robert! This post gets reasonably high traffic, and I’m sure people will be delighted to have that link.
Cheers, Sarah
Hi,
you might be interested in RestDoc a specification to provide computer readable documentations of REST APIs
http://www.restdoc.org
Regards,
Thorsten
Thank you very much, Thorsten! That’s very useful. I’ll share it with my colleagues, and I think other readers of this post will be grateful to you for sharing the link too.
Cheers,
Sarah
Sarah,
If you’re still compiling that list of API generators, take a look at MireDot (wwww.miredot.com) as well. It grew from a tool we developed in house to document our rest interfaces, and is now publically available (free for open source projects).
It’s distributed as a maven plugin and generates its documentation based on existing javadoc tags and jaxrs annotations. At the time of writing, the focus is on JSON (no jaxb yet), but the tool is under active development and we choose the features to implement based on requests and feedback.
Regards,
Yves
Hallo Yves
MireDot looks awesome! Thanks for posting the link here. I love the clean layout of the docs it produces, and the fact that it works off annotations that are already in the code. The smart search in the right-hand panel is pretty cool.
I’ll spread the word by tweeting, and let my colleagues know internally too.
Cheers
Sarah
It seems that all your Atlassian links are dead? At least on mobile, or at least at least for me. 🙂
Was interested in reading about already built guidelines. Have made a few REST APIs, but could definitely get a clearer picture about best practices. Especially for generated resources and actions. 🙂
Hallo velmont
Thanks for the heads up. I’ve updated the post to reflect changes in the Atlassian docs. I hope you find the docs useful!
Cheers
Sarah
Pingback: Search tools for API documentation « ffeathers — a technical writer’s blog