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 AsyncAPI, when consumers need to shape their own queries we govern a GraphQL schema, when we push change outward we define real webhook contracts, and in every case we catalog the event types so nobody has to reverse-engineer what flows through the system. Forcing an asynchronous or streaming reality into a request-response mold creates brittle integrations and endless workarounds, and I have watched teams pay for that mismatch for years. The business gets cleaner interoperability and simpler integrations when the protocol matches the interaction, and our consumers get contracts that tell the truth about how the system behaves.
APIs Use the Right Protocol for the Job
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 ...
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. ...
Webhook Contracts Defined
I require that every webhook an API sends is described by a real contract that specifies its trigger, its payload, its headers, and its delivery and retry behavior, so integrators can build against...
Event Types Cataloged
I require that every event an API emits is enumerated in a published catalog of event types, each with a stable name, a described payload, and a clear meaning, so consumers know exactly what can ha...
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...
Integration
Integrating digital resources and capabilities into other systems using HTTP APIs is commonplace in any enterprise. However, the experience, skills, time, and cost required for successful integrati...
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...
