Designing an API – Documentation

15 Jun 2015

If you haven’t yet seen part 1, this post vaguely follows on from that, whilst the follow up is in part 3.

Documentation of an API is an easy concept to understand, however getting from the state of no-documentation, to a fully documented API is often less straight forward.

API usage falls on a spectrum of open-to-the-world right through to never-used-by-another-sole, however all APIs need some form of documentation, if only to avoid endless trips through an unrelated codebase to see how it works.

The simplest, and often best form of documentation, is tests, and for many limited use-case or internal APIs these are as far as you need go; they tell you everything you need to know about the API and nothing more.

However a number of APIs need go a step further and actually publish documentation, at which point a number of issues arise:

  1. Your documentation has to change every time your API does
  2. You have to host your documentation somewhere online
  3. You have to make sure you actually implement what you laid out in the documentation

If you’re hosting your documentation online and don’t have time to burn I’d highly recommend a Github repository; your developers will know how to update it, other developers will know how to use it, and you’ll be able to see a version history in case you want to revert changes, or see who updated the docs.

Once you’ve gotten a larger user base however and want to do something a little more fancy, here are a few things to bear in mind:

APIs can be a huge boon a project, build one, publish it, then go and write some awesome documentation.