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 need.
Documentation
Rules
APIs.json Apis Properties Documentation Info
This property so that there is documentation published for an API, and API consumers will have a set of human-readable instructions for onboarding and integrating with HTTP APIs in their applications
Strategies
APIs Are Always Well Documented
Documentation is the front door to your API, and I am still amazed at how many teams leave that door half open. Or locked. You need human-readable docs that cover methods, operations, requests, res...
APIs Deliver an Exceptional Developer Experience
Developer experience is where the technology, business, and politics of APIs all converge. Interactive docs, sandbox environments, realistic examples, intuitive naming--when developers can quickly ...
Experiences
Alignment
I see product and engineering teams talking past each other constantly when it comes to APIs. Without alignment on the why behind each API, you end up with technically sound resources that nobody a...
Communication
I struggle with how little communication happens between the teams producing APIs and the people consuming them. Blogs, changelogs, roadmaps -- these are building blocks that most teams just skip, ...
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...
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...
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...
Consistency
When I look across the API landscape, consistency is one of the biggest challenges I see. Every team does things differently, and the surface area of inconsistency just grows until governance becom...