Building better API documentation

A while back, over on the Cogi blog, James announced the public beta of our new public remote API. Designing and implementing this API has been a major focus for our team over the last several months. We've taken our several private interfaces, and refactored and reimplemented them into a single interface that we want to expose to our customers and partners to allow them to develop applications that take advantage of the rich backend systems we've built over the past couple of years.

Now, one of the things with releasing a remote API with consumers beyond your own applications is that the API itself becomes a kind of contract between your service and the new consumers -- a contract that you must both present and maintain. In this post, I'd like to talk about the primary mechanism through which we present our API -- the API documentation.

There is a whole laundry list of things that can go wrong with any API documentation -- for starters, let's consider just this small (and incomplete) list of problems:

• Stale documentation
• Missing documentation
• Documentation that's difficult to interpret
  

An interesting take-away from this is that both of the first two points are related to the documentation not matching the interface that's actually deployed on the server -- that is, if we had a way of connecting that documentation to the service itself, those problems would be less likely to become a problem. So, we decided to introduce the concept of an API "demo" as our documentation.

So, rather than merely describing the interface we provide and expect in some separately maintained documentation, our API documentation actually shows you what to do -- how the call is formed, and what the response looks like. What's more, in the process, it actually demonstrates that the API is actually working as described, because the demo actually makes a call into the API itself! In fact, the API documentation is essentially an automatically generated client of the API itself!

Whats more, since the API documentation is dynamically generated at runtime, we never have to worry about it being out of date, since what is displayed in the documentation exactly matches the code the API server is running from -- that includes the method interface, method documentation, and response API.

Want to try it out? Contact us at api@cogi.com to get an API key and start developing against the Cogi API! Have other thoughts? Leave them in the comments below!