Ensure APIs are discoverable and documented

For APIs to be used, they must be discoverable and documented. Developers often cite the requirement for good documentation as the single most important quality of APIs.


Consider using some sort of literate system that generates the API documentation from API code (or vica verca), to ensure so that there is always a precise alignment between the API and it’s documentation.


Consider using open source API specification tools such as, to simplify and standardise the means by which APIs are documented.