Continuing my quest for the perfect API documentation, this week I came across a site that offers a search over a set of API documents: Rails Searchable API Doc. Have you seen it before, or anything similar or even better?
I’ve written a couple of posts recently about API documentation, talking about documenting REST APIs and using tests as examples. People have added a lot of very useful and thought-provoking information via comments on both posts. Thank you everyone! This time, I’d like to show you a site that Jean-Michel pointed me at.
sdoc for searching Ruby APIs
The Rails Searchable API Doc site is developed by Vladimir. As the name implies, you can use the site to search the Ruby on Rails API documentation. The site is built by Vladimir’s tool sdoc, that adds a search feature into the documentation generated by RDoc. RDoc builds HTML documentation from Ruby source code.
Vladimir’s sdoc code repository is on Github. Here’s the readme.
Try it out!
Go to http://railsapi.com/. Here’s the gist of what you will see:
Select one of the options above the big buttons, to choose the APIs that you want:
- Rails and Ruby
- Build your own
If you choose to build your own, you will get a list of APIs to choose from:
Make your choice, click “Browse online” to see the API documentation, then enter a search term to see the dynamic search working. It’s in the left-hand panel:
What I like about this search is that it’s immediate. You see the results as you type. A very nice addition is that you can select one or more sets of API documentation to merge into the search.
The search is smart. The first few results show matches that start with the search term you entered. Then come the results where your term is embedded somewhere in the string. Finally it shows results that may be a match: the characters in your search term appear in the result, but not necessarily sequentially. The front page has a quick guide to the features of the search tool.
Pretty neat, huh.
I want an sdoc!
I’m wondering how much sdoc relies on the RDoc format, and how easy it would be to adapt it for documentation generated by other tools such as Jersey’s WADL generator, Javadoc, Sandcastle for .NET, Doc-O-Matic, Enunciate, Doxygen. I’ve written to Vladimir, asking him for his thoughts on this.
Have you seen similar search tools on other API documentation sites?
BTW, a good API doc site
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.