All API parameters must have clear names, descriptions, types, and constraints following consistent casing and naming conventions, with reusable parameters centralized in OpenAPI components to reduce duplication and ensure uniformity across operations.
API Parameters Are Well-Defined and Consistent
Policies
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 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.
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.
Centralizing Parameters Using Components
Centralizing parameters in OpenAPI components is how you stop repeating yourself. Define a parameter once, reference it everywhere, and governance gets simpler.
Experiences
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...
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...
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...
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...
Reusability
I watch teams rebuild the same patterns, schemas, and components from scratch over and over again. Reusability is one of the promises of APIs that we still haven't delivered on, and it's where a lo...