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