The schema for data that is sent and received via API should always be well-defined, possess a well-known shape, and always be validated, ensuring that digital resources and capabilities are what they should be, and only accessible to those who should have access our API digital resources.
Data Should Be Well-Defined and Validated
Policies
Schema Type
Every schema needs a type. Without it, validation tools and code generators can not do their job, and consumers have no way to know what shape of data to expect.
Schema Names
Schema names should follow consistent casing conventions and be descriptive enough that you know what they represent without reading the properties. Pascal case is what I see working best.
Schema Descriptions
Schema descriptions tell consumers what each data structure represents. Without them, people are left reading property names and trying to infer the meaning of the whole object.
Schema Properties
Schema properties are the individual data points that flow through your API. Having them well-defined with types, descriptions, and constraints is how you prevent data quality issues.
Schema Property Names
Property names are part of the contract consumers code against. Consistent casing, reasonable length, and meaningful names make the difference between an API that is intuitive and one that is frust...
Schema Property Descriptions
Property descriptions explain what each field means in context. This is especially important for fields where the name alone does not tell the full story.
Schema Property Type
Property types define what kind of data each field holds. Getting the types, formats, and array item definitions right is fundamental to an API that works predictably.
Schema Property Shapes
Property shapes -- min and max lengths, array bounds, number ranges -- define the constraints on your data. These constraints are what prevent garbage data from flowing through your APIs.
Schema Constraints
Schema constraints like min, max, minLength, maxLength, and enum values are the guardrails on your data. Without them, anything can flow through your API and garbage in means garbage out.
Schema Required Properties
Marking required properties in your schema objects tells consumers and validators which fields must be present. This prevents incomplete data and makes API interactions predictable.
Data Types and Formats
Consistent data types across APIs prevent integration headaches. ISO 8601 for dates, standard number formats, and proper OpenAPI format specifiers mean data serializes the same way everywhere.
Data Validation
Data validation at the API boundary catches problems before they propagate. Type checking, format enforcement, required fields, and enum validation are the building blocks of data integrity.
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...