Blog Archives

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

Writing REST API documentation

%d bloggers like this: