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
Requiring that all schema type meets the policy standards.
Schema Names
Requiring that all schema names meets the policy standards.
Schema Descriptions
Requiring that all schema descriptions meets the policy standards.
Schema Properties
Requiring that all schema properties meets the policy standards.
Schema Property Names
Requiring that all schema property names meets the policy standards.
Schema Property Descriptions
Requiring that all schema property descriptions meets the policy standards.
Schema Property Type
Requiring that all schema property types meets the policy standards.
Schema Property Enums (OpenAPI)
Require that any property with a fixed set of allowed values declares those values as an enum in the schema, so status, type, and category fields cannot drift into a free-for-all of typos and inven...
Schema Property Required (OpenAPI)
Require that our schemas explicitly list which properties are required, so consumers know which fields they can always count on and which ones may be absent. I have written code that trusted a fiel...
Schema Property Shapes
Requiring that all schema property shapes meets the policy standards.
Schema Constraints (OpenAPI)
Require that our schemas express real constraints on their properties, the minLength and maxLength, minimum and maximum, patterns, and formats that describe what valid data actually is rather than ...
Schema Required (OpenAPI)
Require that every request and response body in our OpenAPI definitions references a defined schema rather than accepting or returning free-form, untyped content. I have run into operations that de...
Data Types (Design)
Require that every property in an API contract declares an explicit, well-chosen data type with the right format, precision, and constraints instead of leaning on loose strings and hopeful parsing....
Validation (Design)
Require that every API defines and enforces validation rules in its contract, using schemas, constraints, required fields, and formats so that bad input is rejected with a clear, consistent error i...
Experiences
Access
Gaining the necessary access to effectively use an API is often more challenging than it appears. Intentional and unintentional barriers can create friction in discovering and onboarding with an AP...
Automation
Automating business operations is a primary driver for adopting and governing APIs, enabling organizations to achieve the scale, speed, and quality needed to remain competitive in global markets. A...
Communication
Consistent communication about the production and consumption of APIs is critical for effective enterprise governance. APIs are inherently difficult to visualize, making it essential to invest in m...
Consistency
Achieving consistency in the design, delivery, and maintenance of HTTP APIs across an enterprise is a significant challenge—one that often complicates API operations. Small differences, such as var...
Discovery
The average enterprise maintains approximately 0.5 APIs per employee, making it a constant challenge to track the growing inventory of HTTP APIs being produced and consumed. Enterprises often addre...
Onboarding
Transitioning from API discovery to integration as a consumer requires a well-defined and streamlined API onboarding process. Onboarding begins with discovery and relies heavily on clear documentat...
Quality
The quality of HTTP APIs powering an enterprise tends to decline as the number of ungoverned APIs grows across internal, partner, and public landscapes. Low-quality APIs lead to poor downstream exp...
Reliability
If an API isn’t reliable, consumers will eventually look for alternatives. Reliability starts with the platform and infrastructure where the API is deployed, but it also depends heavily on the pace...
Security
API security is a top priority for any enterprise, with even higher standards for externally available APIs. However, security doesn’t end with the APIs an enterprise produces—it also applies to co...
Self-Service
Self-service is the experience of a consumer being able to discover, access, and integrate an API without having to talk to a human. Portals, sign-up flows, documentation, and keys let developers g...
Simplicity
Simplicity is a hallmark of well-designed HTTP APIs, but achieving simplicity requires effort. The likelihood that a partner or third-party developer will abandon an API increases as cognitive load...
