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 talk to another without custom glue code for every connection. The more interoperable an API is, the more places it can be used and the more value it can create. I care about interoperability because it is what turns a collection of individual APIs into a platform. When providers embrace open specifications and consistent patterns, consumers can compose capabilities across many APIs the way they would snap together building blocks. Every proprietary shortcut that breaks interoperability is a tax paid by everyone downstream.
Interoperability
Policies
AsyncAPI Contracts Provided
I require that any event-driven or messaging interface is described with an AsyncAPI document, the same way we insist on OpenAPI for request-response APIs, so that channels, messages, and payloads ...
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...
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....
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...
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...
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....
GraphQL Schema Governed
I require that any GraphQL API ships a published, versioned schema that we govern like any other contract, with consistent naming, deliberate types, and a clear boundary on what the graph exposes. ...
Open Standards Adopted
Require that APIs are defined and delivered using open standards such as OpenAPI, AsyncAPI, and JSON Schema rather than proprietary formats. Open specifications lower the cost of adoption, enable i...
HTTP Methods (OpenAPI)
Require that every operation in an OpenAPI definition uses the correct HTTP method for the action it performs, GET to read, POST to create, PUT and PATCH to update, DELETE to remove, and that we do...
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...
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...
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...
Strategies
API Errors Are Standardized and Informative
All API error responses must follow standardized formats like RFC 7807 Problem Details, providing consistent error codes, human-readable messages, and correlation IDs that enable consumers to progr...
APIs Are Interoperable Across Systems
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 reducin...
APIs Avoid Vendor Lock-In
Lock-in is a choice, and I want API operations to choose against it. Building on open standards, avoiding proprietary traps, and giving consumers a clear way out are what let people commit to an AP...
APIs Follow Consistent Design Patterns
All APIs must follow consistent design patterns for naming conventions, media types, pagination, filtering, sorting, and error handling, ensuring that consumers can learn patterns once and apply th...
APIs Prefer Open Standards and Open Source
Every proprietary shortcut an API takes becomes a tax paid by everyone downstream. I want API operations to prefer open standards like OpenAPI, AsyncAPI, and JSON Schema, and to lean on open source...
APIs Support Event-Driven and Asynchronous Patterns
APIs that require event-driven or asynchronous communication must follow consistent standards for webhook registration, payload formats, retry policies, and delivery guarantees, enabling reliable a...
APIs Use the Right Protocol for the Job
I want us to stop treating REST as the answer to every problem and instead pick the protocol that actually fits the job in front of us. When the interaction is event-driven we describe it with Asyn...
