All APIs must prioritize interoperability by using standard media types, hypermedia link relations, and well-known specifications, enabling consumers to integrate multiple APIs together and reducing vendor lock-in and rework when switching between providers.
APIs Are Interoperable Across Systems
Policies
Media Types (Design)
Require that every request and response declares an accurate, standard media type, and that content negotiation is handled deliberately rather than assumed to always be JSON. Every API must be expl...
Hypermedia (Design)
Require that APIs return links alongside their data where it helps consumers navigate related resources, discover available actions, and follow state transitions without hardcoding URLs. APIs shoul...
Compatibility (Design)
Require that changes to an API preserve backward compatibility by default, and that any deviation is a deliberate, governed decision rather than an accident of a merge. Every API must be designed s...
Robustness (Design)
Require that APIs are designed for robustness on both sides of the wire, being conservative in what they send and tolerant in what they accept, so that small variations do not cascade into outages....
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....
Standards
Internet, industry, market, and government standards help make APIs more consistent, but also save time and money for both producer and consumer, while keeping APIs better aligned with existing ind...
HTTP
The Hyper Text Transfer Protocol (HTTP) from the IETF.
JSON
Using the JavaScript Object Notation (JSON) format.
JSON Schema
Using the JSON Schema to define and validate models.
OpenAPI
Using the OpenAPI specification to describe HTTP APIs.
Providing External Document References
Requiring that all OpenAPI external documentation meet the policy standards.
Experiences
Interoperability
Interoperability is the experience of APIs, systems, and data working together without heroic effort. It is built on shared standards, common schema, and predictable contracts that let one system t...
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...
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...
Developer Experience
Developer experience is the sum of every interaction a developer has with an API, from the first time they land on the portal to the hundredth time they call an endpoint in production. It covers do...
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...
