Documentation¶
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.
Recommended
Publish API documentation, and provide a link to the documentation from the API endpont.
Recommended
Provide feedback and support channels for API users.
May
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.
May
Consider using open source API specification tools such as http://swagger.io/, to simplify and standardise the means by which APIs are documented.
Recommended
All APIs that are published should be adequately documented and supported by the agency that produces them.