Building and documenting apis for discoverability

Goals

• Findability - Developers must be able to find the initial entry point to your API docs and your actual API
• Discoverability
  • Human - Developers should be able to easily learn how to use your API through documentation, adherence to standards, and good intuition
  • Programattic - Applications should be able to programmatically determine the capabilities of your API through introspection

These same concepts adhere to both internal company APIs as well as open public APIs.

Tools

• Swagger
• mashery/iodocs
• Apigee
• Hypermedia Forms
• kevinswiber/siren
• Collection+JSON - Hypermedia Type : Media Types
• JSON Schema and Hyper-Schema
• JSON-LD - JSON for Linking Data
• Rest.li

Techniques

• Be opinionated in your frameworks to push developers down the best path, but allow them to use only the portions they find most useful, if they have their own frameworks
• Build docs automatically, but augment with tutorials and authored examples
• Make docs tutorial-oriented
• Provide a big, obvious "API HERE!!!" entry point to your dev docs
• Be consistent in your query parameters, data formats, and paging techniques
• Be consistent in your functional docs
  • Question: Do APIs need JavaDoc-style standards for doc formats?
• Provide documentation about design intents, in order to help developers understand why certain design decisions were made
• Consider standards such as OData or SODA
• Provide URI templates
• Keep your documentation fun and engaging (http://httpstatusdogs.com)
• Make your internal developers use your own documentation. Don't answer emails!
• Link out to standards where appropriate.
• Make your API friendly to experimentation with cURL and simple tools
• Allow external developers to submit pull requests with edits or tutorials
• Use developer feedback!