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
Media types define the content formats your APIs support. JSON is the default I see across the landscape, but having a clear policy for content negotiation prevents confusion when multiple formats ...
Hypermedia
Hypermedia links in API responses let clients discover what actions are available dynamically. It reduces the coupling between clients and servers and makes APIs more self-describing and navigable.
Backwards Compatibility
Backwards compatibility is how you evolve APIs without breaking the consumers who already depend on them. Adding optional fields is fine. Removing or renaming published endpoints is not.
Robustness Principle
The robustness principle -- be liberal in what you accept, conservative in what you send -- is old wisdom that still applies. It keeps APIs forward-compatible and resilient to the messiness of real...
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.
Standards
Standards are the building blocks that save everyone time and money. HTTP, JSON, OpenAPI, JSON Schema -- adopting these keeps APIs consistent and interoperable without reinventing the wheel.
HTTP
HTTP from the IETF is the foundation that the entire API landscape is built on. Understanding and properly using HTTP is not optional -- it is the baseline for everything.
JSON
JSON is the lingua franca of APIs. It is the format that most of the API landscape has settled on for exchanging data, and understanding its conventions matters.
JSON Schema
JSON Schema gives you a standard way to define and validate data models. It shows up everywhere in the API landscape -- in OpenAPI, in validation, and in contract testing.
OpenAPI
OpenAPI is the specification I see driving the most consistency across the API landscape. It is the foundation for documentation, governance, code generation, and testing.
Providing External Document References
External documentation references in OpenAPI connect the technical contract to the broader context. Linking out to guides, tutorials, and background docs gives consumers a fuller picture.
Experiences
Interoperability
Interoperability is where standards really earn their keep in the API landscape. When every API uses different formats, patterns, and conventions, consumers pay the tax every time they try to integ...
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...
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...
Developer Experience
Developer experience is the thing I'm most passionate about across the API landscape. Poor docs, missing examples, inconsistent patterns, and no tooling -- these are the things that make developers...
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...