UI Deploy

So you’ve built yourself an API. Perhaps it’s RESTful, RESTlike or something else entirely. You’ve implemented authentication – be it using OAuth, HTTP Basic Auth or JSON Web Tokens. You’ve fashioned your responses using JSON, maybe XML, or even something else. Your unit and integration tests are passing, you may have a third-party service such a Runscope testing it periodically, or using JSON or XML schemas to validate your responses.

There’s one more thing, however.

Thing is, an API is only as good as its documentation. That applies if it’s for internal use only – perhaps it’s for a JavaScript-based one-page app, or a mobile application – but even more so if it’s for public consumption.

There are a number of ways in which you can put together your documentation. For the purposes of this article I’ll assume it’s web-based, whether it’s publicly available over the internet or privately held on a company intranet.