An API is only as good as its documentation.
Your APIs are only as good as the documentation that comes with them. Invest time in getting docs right. — @rubenv on Twitter
If you are in the business of shipping software, chances are high that you’ll be offering an API to third-party developers. When you do, it’s important to realize that APIs are hard: they don’t have a visible user interface and you can’t know how to use an API just by looking at it.
For an API, it’s all about the documentation. If an API feature is missing from the documentation, it might as well not exist.
Sadly, very few developers enjoy the tedious work of writing documentation. We generally need a nudge to remind us about it.
At Ticketmatic, we promise that anything you can do through the user interface is also available via the API. Ticketing software rarely stands alone: it’s usually integrated with e.g. the website or some planning software. The API is as important as our user interface.
To make sure we consistently document our API properly, we’ve introduced tooling.
Similar to unit tests, you should measure the coverage of your documentation.
After every change, each bit of API endpoint (a method, a parameter, a result field, …) is checked and cross-referenced with the documentation, to make sure a proper description and instructions are present.
The end result is a big documentation coverage report which we consider as important as our unit test results.
Constantly measure and improve the documentation coverage metric.
More than just filling fields
A very important things was pointed out while circulating these thoughts on Twitter.
Shaun McCance (of GNOME documentation fame) correctly remarked:
@rubenv I’ve seen APIs that are 100% documented but still have terrible docs. Coverage is no good if it’s covered in crap. — @shaunm on Twitter
Which is 100% correct. No amount of metrics or tooling will guarantee the quality of the end-result. Keeping quality up is a moral obligation shared by anyone in the team and that can never be replaced with software.
Nevertheless, getting a slight nudge to remind you of your documentation duties never hurts.