API and Web service Documentation the manual way really sucks. With every tiny change you need to remember to update your documentation (site) and its almost definite that you forget something.
Plain said .. Your docs are always outdated! But that is by far the only documentation pain.
How about:
- inform users about changes
- let users participate
- docs in different format & devices
- make them fun to read
- link to docs from your wiki or support emails?
This article is from our series on API-Building. I assume you already know JSON Schema because the answers mostly rely on it.
Help, my API Documentation is outdated!
Don’t panic .. just stop writing it. The basic problem of decoupled (public) docs and code, has long been solved in all programming languages. Documentation generator like rdoc, javadoc or phpdoc crawl source-code comments and create HTML pages. But for a web-API this does not work, as there is no single piece of code involved. And you probably don’t want to share all internals(models, libs, controllers) with the general public. Instead write a JSON-Schema as decoupled API meta-description. JSON itself is already pretty readable but with a few lines of code(or a ruby gem) generating a nice website is a breeze.
Our API Explorer for SalesKing, also available on github
Important: DON’T write a schema just for documentation. Your software should also rely on it internally, for example to parse incoming and outgoing data. Only by those means your are forced to update the schema on every API change. ( HowTo will follow).
I forgot to notify API clients about updates
Whether you are spamming users for every little typo, or not sending update information at all, coders will always complain. The key to success is to OpenSource your schema files on a plattform like github. Let them handle the changes in terms of history, commits or file-diffs and leave it up to API clients to subscribe updates. Even more important is the fact that users can see changes before they are implemented in your live instance. Branches, tags, version numbers or simple folders are your friend.
An advanced option is to pack your schema in a distributable library. Connected software is automatically updated whenever you bump a new version. We did it as ruby gem: sk_api_schema. Your language of choice probably has something similar, like eggs in Pythons or PEAR in PHP.
Don’t be tempted to upload your HTML API-docs! Reading html file diff’s lead to eye cancer. So please, just go with plain pretty formatted JSON files.
Share the love
Open-sourcing an API description leads to unbeaten transparency, actually is the most missing feature in webservice API’s.
Github and others, sport further features to stay in contact with your API community. The obvious are comments, bug reports and a wiki, tackling help requests and informational shortages. Productivity boosters like (git-based) fork, pull-request and merge mechanisms serve to incorporate 3rd party developers. Besides all of those, my favorite feature is sending source-code links via email or skype.
Make them easy to link
In lengthy HTML websites, one uses anchors or pages to describe a specific API field or aspect. Still i have seen lots of docs(PDF shine here) where a user has to search a long page, instead of having a specific direct link. This is a breeze on github: simply go to a file, click the line number and you have the URL. For example: It happens frequently that users ask me about available payment mehods .. this is the answer link
Mobilize your docs
Docs should not be tied to a single display technique. There are template generator tools, compiling the documentation as PDF, single page HTML or multipage website. As of my knowledge and as mentioned before, they rely on comments in the source code.
On a simple foundation like JSON Schema, you can build your own output generator in less than 10 lines of code. If you are using ruby, a quick stub could look like this (dots . visualize HAML indentation):
%h2= @schema[‚title‘]
– @schema[‚properties‘].each do |name, defs|
..%h4= name
..%dl
..- defs.each do |key, val|
….%dt= key
….%dd= val
For our current API browser, we choose to go with bootstrap’s responsive layout and added media queries to optimize the layout for mobiles and tablets. A filter for classes and fields at the top, eases finding and by using TAB you save mouse moves. Under the hood we are using a Sinatra, jQuery and SalesKing’s API schema gem. The API browser is by far final, as it was quickly hacked on a day. But it shows that it does not need a lot to build an accessible, self updating API docs website.