All APIs must prioritize the developer experience by providing interactive documentation, sandbox environments, realistic examples, and intuitive naming, ensuring that developers can quickly understand, experiment with, and successfully integrate APIs with minimal friction.
APIs Deliver an Exceptional Developer Experience
Policies
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...
Sandbox (Experience)
Require that every API offers a sandbox environment with test credentials and safe, representative data so a developer can experiment fully before touching production. I champion sandboxes because ...
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 ...
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...
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.
Getting Started
The step by step walk-through for new API consumers, ensuring they have exactly what is needed to discover and onboard, but also help make sure the getting started steps are as simple, plain langua...
Getting Started Authentication
Needs description.
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.
SDKs (Getting Started)
Provide a link and description of where API consumers can get access to SDKs, libraries, and the code that will jumpstart their integration with an API.
Experiences
Developer Experience
Developer experience is the sum of every interaction a developer has with an API, from the first time they land on the portal to the hundredth time they call an endpoint in production. It covers do...
Onboarding
Transitioning from API discovery to integration as a consumer requires a well-defined and streamlined API onboarding process. Onboarding begins with discovery and relies heavily on clear documentat...
Self-Service
Self-service is the experience of a consumer being able to discover, access, and integrate an API without having to talk to a human. Portals, sign-up flows, documentation, and keys let developers g...
Simplicity
Simplicity is a hallmark of well-designed HTTP APIs, but achieving simplicity requires effort. The likelihood that a partner or third-party developer will abandon an API increases as cognitive load...
Quality
The quality of HTTP APIs powering an enterprise tends to decline as the number of ungoverned APIs grows across internal, partner, and public landscapes. Low-quality APIs lead to poor downstream exp...
Discovery
The average enterprise maintains approximately 0.5 APIs per employee, making it a constant challenge to track the growing inventory of HTTP APIs being produced and consumed. Enterprises often addre...
