All individual API operations must be useful and follow consistent Internet, industry, and enterprise standards, providing a simple and relevant HTTP API operation that does one thing and does it well, making the value intuitive to API consumers who will be using each API operation.
Operations Must Be Useful and Consistent
Policies
Unique Identrifiers for API Operations
Operation IDs give each endpoint a unique, machine-readable name. SDKs, code generators, and documentation tools all depend on these being consistent and meaningful.
Operation Summary
Operation summaries are the short labels consumers scan when browsing documentation. They need to be concise, descriptive, and follow consistent patterns across all operations.
Description of API Operations
Operation descriptions are where you explain what each endpoint actually does. A missing or weak description means consumers have to guess, and guessing leads to bad integrations.
Request Bodies
Request bodies are one of the most complex parts of an API to get right. Descriptions, required fields, content types, and validation all need to be present and consistent.
Request Bodies Media Types
Media types on request bodies tell consumers what content types the API accepts. Getting this right avoids the confusion that comes when JSON and form data expectations do not match.
Request Bodies Schema
Schema definitions on request bodies are how you validate what consumers send. Referencing shared schemas and requiring bodies on POST and PUT keeps things predictable.
Parameters
Parameters are the inputs consumers use to customize their API calls. Componentizing them keeps things consistent across operations and makes the whole surface area easier to govern.
Parameter In Query or Path
Specifying whether a parameter goes in the query string, path, or header seems basic, but getting it wrong causes real confusion. This needs to be explicit and correct.
Parameter Names
Parameter names are part of your API's surface area that consumers interact with directly. Consistent naming, proper casing, and reasonable length all matter here.
Parameter Descriptions
Parameter descriptions tell consumers what each input actually means and how to use it. Without good descriptions, parameters are just names that people have to reverse-engineer.
Parameter Types
Getting parameter types right -- integers, strings, arrays, numbers -- with proper formats and constraints prevents a whole category of integration bugs before they happen.
Parameter Schema
Schema definitions on parameters give you type safety and validation. Referencing shared schemas keeps things consistent and makes governance rules easier to apply.
Parameter Enumerators
Enumerators on parameters tell consumers exactly what values are valid. This is way better than letting people guess and get back cryptic error messages.
Operation Tags
Tags on operations organize endpoints into logical groups. They drive how documentation is structured and how consumers discover related functionality within an API.
Operation Security
Security definitions on operations make access requirements explicit. Every operation should clearly state what authentication and authorization is required to call it.
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...
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, ...
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...
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...
Reliability
Reliability is where the rubber meets the road in the API landscape. If your APIs aren't up when consumers need them, and if new versions don't land smoothly, none of the other building blocks matter.
Security
Security is the area where I see the most gap between what teams think they have covered and what's actually happening. The surface area of APIs keeps growing, and most organizations aren't keeping...
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...