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
Interactive documentation with try-it-out functionality lets consumers test API calls right from the docs. This removes the gap between reading about an API and actually experiencing how it works.
Sandbox Environments
Sandbox environments let consumers explore and test APIs without any risk. Mock servers, sandbox credentials, and sample data are building blocks that accelerate onboarding and reduce integration t...
Localization
Localization support in APIs means respecting Accept-Language headers, regional date formats, and translated messages. If your API serves a global audience, this is how you meet them where they are.
Documentation
Documentation is the human-readable representation of your API's surface area. Paths, methods, descriptions, examples -- this is where consumers go to understand what is possible and how to get sta...
Documentation Examples
Examples are where documentation goes from theoretical to practical. Showing real request and response variations helps developers understand what is actually possible with an API.
Documentation Paths
Clean, intuitive paths in your documentation make a big difference. If consumers can not quickly scan and understand the URL patterns, they are going to struggle with the rest.
Documentation Request Bodies
Request bodies are where consumers need the most hand-holding. Clear details and examples for POST and PUT payloads prevent a lot of frustration and support tickets.
Documentation Responses
Every response needs a complete example in the docs, including the unhappy paths. Developers need to know what success looks like and what happens when things go wrong.
Documentation Schema
Documenting your schema objects is how you give consumers the full picture of what data flows through the API. JSON Schema representations make this concrete and referenceable.
Getting Started
Getting started is the single most important thing you can get right for new API consumers. A simple, plain language walkthrough that covers discovery, onboarding, and first API call makes or break...
Getting Started Authentication
The getting started experience needs to cover authentication clearly. If a new consumer can not figure out how to authenticate quickly, you have already lost them.
Getting Started Documentation
Pointing new consumers to your documentation is the first step in getting started. This is the entry point where they begin learning what the API does and how to use it.
SDKs (Getting Started)
Including SDKs in your getting started flow gives consumers a head start. Pointing them to client libraries and code they can use right away removes a lot of friction from onboarding.
Experiences
Developer Experience
Developer experience is the thing I'm most passionate about across the API landscape. Poor docs, missing examples, inconsistent patterns, and no tooling -- these are the things that make developers...
Onboarding
I see teams dealing with massive friction during onboarding. If a consumer can't get from zero to their first successful API call in minutes, you've already lost them. Getting started guides, sandb...
Self-Service
Self-service is the goal I keep pushing teams toward. If a consumer can't find your API, sign up, get keys, and make their first call without emailing someone, you've created a bottleneck that will...
Simplicity
I am a big believer that the best APIs are the simple ones. When I see overly complex API designs, I know someone was thinking about their internal architecture instead of the consumer. Keep the su...
Quality
I see the quality of APIs eroding across the landscape. Teams ship fast and never look back, but consumers feel every rough edge, every missing example, every inconsistent response. Quality is what...
Discovery
Discovery is the dark matter of the API landscape. Teams build APIs that already exist somewhere else, and consumers can't find the APIs they need. Without a catalog and proper metadata, you're jus...