Documentation is the API for humans. I generate reference docs from the definition and surround them with the guides, examples, and getting-started material that turn a spec into understanding. Documentation is where most APIs quietly succeed or fail at being adopted.
Documentation
Beta
Stop 12
Policies at this stop
API Education and Enablement
Require that an API invests in educating and enabling its consumers through tutorials, guides, and clear explanations of not just how it works but why. Most friction around APIs comes from gaps in ...
Descriptions for APIs
Providing a robust description of each API, providing the right amount of information for consumers to understand what is possible and what the business use case is.
Descriptions for APIs.json Contracts
Providing a robust description of the API contract, as well as each API it contains, providing my context for stakeholders of the contract.
Documentation Examples
Providing examples of request and responses, with as many variations as possible, helping demonstrate wide usage of an API.
Documentation Paths
Providing simple, clean, and intuitive paths as part of the documentation being published for consumers to use.
Documentation Request Bodies
Including details and examples regarding the request bodies being submitted for POST, PUT, and other possible methods.
Documentation Responses
Making sure there is a complete example for each API response in documentation, including happy and unhappy responses.
Documentation Schema
Documenting all of the schema which are used as part of request bodies and responses, providing JSON SChema representations of each.
Documentation
The human-readable HTML, Markdown, or PDF representation of the technical surface area of each API, providing path, methods, summaries, description, examples, and the other resources consumers will...
Interactive Documentation (Experience)
Require that every API ships interactive documentation generated from its contract, where a developer can read the operations, see the schemas, and make a real call right from the page. I have beli...
Localization (Experience)
Require that APIs serving a global audience localize the things developers and end users actually experience, from documentation and portal content to error messages, currencies, and date and time ...
Migration Guides (Experience)
Require that whenever an API version is deprecated or a breaking change is introduced, a clear migration guide is published that shows consumers exactly how to move from the old to the new. I insis...
Getting Started Documentation
Provide a link and description to your API documentation, providing the entry point for API consumers to begin learning about what your API does.
GitHub Organization README
GitHub organization provide the ability to have a dedicated README, providing a single landing page for the API workspace of a domain, line of business, or domain, where all API contracts can be fo...
Providing External Document References
Requiring that all OpenAPI external documentation meet the policy standards.
Description of APIs
Requiring the info description property meets the policy standards.
Description of API Operations
Requiring that all operational descriptions meets the policy standards.
Parameter Descriptions
Requiring that all operational parameters descriptions meets the policy standards.
Request Bodies Examples
Requiring that all operational request body examples meets the policy standards.
2xx Response Examples (OpenAPI)
Require that every successful 2xx response in our OpenAPI definitions includes at least one realistic example, so a consumer can see exactly what a good answer looks like without making a live call...
4xx Response Examples (OpenAPI)
Require that our 4xx client-error responses carry real examples, so a developer can see exactly what a validation failure, an unauthorized call, or a missing resource actually returns. I have spent...
Schema Descriptions
Requiring that all schema descriptions meets the policy standards.
Schema Property Descriptions
Requiring that all schema property descriptions meets the policy standards.
README
Require that each API contract repository has a dedicated README.
