A machine-readable OpenAPI using the most recent version of the API specification, describing the surface area of each API, which is then used to render the human-readable documentation, and other supporting elements.
OpenAPI
Rules
APIs.json Apis Properties OpenAPI Info
This property so that there is an OpenAPI present for an API, giving the technical contract that describes the surface area of an API
Strategies
APIs are Defined by Technical Contracts
Every API needs machine-readable artifacts that define what it actually does. OpenAPI, JSON Schema--these make your APIs tangible, testable, and discoverable. Without them, you are just describing ...
Experiences
Access
I keep seeing teams struggle with getting consumers proper access to their APIs. The sign-up, authentication, and authorization process is where you lose people before they ever make their first AP...
Automation
I keep shining a light on automation because it's the only way to scale API operations. When testing, validation, deployment, and governance are all manual, you're just adding human error and slowi...
Change
Change is the one constant across the API landscape, and I watch teams struggle with it every single day. If you aren't actively managing and communicating change across versions, deprecations, and...
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...
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...
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...