All API responses should follow Internet, industry, and enterprise standards, providing a meaningful and consistent communication and structure, always providing what was intended for API consumers, while ensuring things are always as simple as possible--always reducing the cognitive load.
API Responses Must Be Meaningful and Consistent
Policies
Response 2xx
Requiring that all 2xx responses meets the policy standards.
2xx Response Media Types (OpenAPI)
Require that every 2xx response declares the media types it returns, spelling out application/json or whatever content it actually serves rather than leaving the content negotiation a mystery. I ha...
2xx Response Schema (OpenAPI)
Require that every 2xx response defines a schema for its body, describing the exact shape, properties, and types a consumer will receive on success rather than handing back an undocumented blob. I ...
2xx Response Examples (OpenAPI)
Require that every successful 2xx response in our OpenAPI definitions includes at least one realistic example, so a consumer can see exactly what a good answer looks like without making a live call...
Response 4xx
Requiring that all 4xx responses meets the policy standards.
4xx Response Media Types (OpenAPI)
Require that every 4xx client-error response declares its media type, so consumers know whether an error comes back as application/json, application/problem+json, or something else entirely. I have...
4xx Response Schema (OpenAPI)
Require that our 4xx client-error responses define a schema, ideally a consistent error object with a code, a message, and enough detail for a consumer to understand what went wrong and how to fix ...
4xx Response Examples (OpenAPI)
Require that our 4xx client-error responses carry real examples, so a developer can see exactly what a validation failure, an unauthorized call, or a missing resource actually returns. I have spent...
Response 5xx
Requiring that all 5xx responses meets the policy standards.
5xx Response Media Types (OpenAPI)
Require that every 5xx server-error response declares its media type, so that even when our own infrastructure fails, consumers still receive a predictable, parseable body instead of whatever a pro...
5xx Response Schema (OpenAPI)
Require that our 5xx server-error responses define a schema, reusing the same standardized error object we use elsewhere so a consumer can handle our failures the same way they handle everything el...
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...
