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 explicit about the formats it accepts and produces, use registered media types, and reserve vendor-specific types for cases that genuinely need them. I have hit too many endpoints that lied about their content type or silently ignored the Accept header, and that ambiguity breaks tooling and interoperability. Getting media types right is a small, unglamorous discipline that keeps our APIs consistent and lets clients across many languages and platforms integrate without surprises.
Media Types (Design)
Strategies
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 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...
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...
Contracts
Every API is a contract, and the contract experience is about how clearly the promises between provider and consumer are expressed. Technical contracts like OpenAPI and AsyncAPI describe what the A...
Lifecycle
design_services Design Design
Design is where the human experience of an API is won or lost. I work design-first, shaping the paths, schema, errors, and naming in the contract before development begins, so that consistency is b...
