API strategy
Platform integration
AsyncAPI vs OpenAPI compared: how each spec works, where each one fits, and how to split a SaaS platform between synchronous and event-driven APIs.
Most SaaS platforms end up needing both. The question isn't which specification is better in the abstract — it's which one describes the surface you're actually building, and where the boundary between them sits.
This comparison is for platform engineers, API leads, and heads of platform trying to pick a specification (or split their platform between two). The decision hinges on one thing: whether the interaction you're documenting is a request the caller initiates and waits on, or an event the platform emits when something changes.
Short version: OpenAPI describes synchronous, request-response HTTP APIs. AsyncAPI describes event-driven APIs — webhooks, message queues, WebSockets, Kafka topics, Server-Sent Events. If your platform has both surfaces (and most do), you'll end up with both specs. The interesting question is where to draw the line.
OpenAPI is a specification for describing HTTP APIs. You write a YAML or JSON document that lists your paths, methods, request bodies, response schemas, authentication, and errors. The current version is 3.2 (released September 2025), which builds on 3.1's alignment of the schema language with JSON Schema draft 2020-12.
The model is request-response. A caller sends an HTTP request to a specific path with a specific method, and the server returns a response with a status code, headers, and a body. OpenAPI describes both sides of that exchange in enough detail that tools can generate SDKs, mock servers, documentation portals, and validation middleware from the spec alone.
The ecosystem is the strongest part. Every major API gateway, documentation platform, SDK generator, and testing tool reads OpenAPI. Contract-first workflows are well-supported: you can write the spec, generate the server stubs and clients, and use the same document to gate CI on breaking changes. It's also the format most AI agents consume when they're introspecting an API surface — see what is OpenAPI for the deeper walkthrough.
Where OpenAPI stops: anything the server initiates. If your platform pushes a webhook when a customer's subscription renews, OpenAPI 3.1 introduced a webhooks object that can describe the payload — but it doesn't model the delivery contract, the subscription mechanism, the retry semantics, or the fact that the caller is now a receiver. The webhooks object was a partial concession to event-driven reality. It didn't solve it.
AsyncAPI is a specification for describing event-driven and asynchronous APIs. You write a YAML or JSON document that lists your channels, the messages that flow through them, the operations (send / receive) attached to each channel, and the underlying protocol. The current version is 3.1 (released January 2026), a non-breaking minor over 3.0, which was released in December 2023 and introduced the cleaner separation between channels and operations.
The model is message-oriented. Instead of paths and methods, you describe channels — abstract addresses where messages are published or consumed. A channel might be an MQTT topic, a Kafka topic, an AMQP queue, a WebSocket route, or a webhook endpoint. AsyncAPI is protocol-agnostic at the top level and uses protocol-specific bindings to describe the transport details.
The format looks familiar if you know OpenAPI — same YAML structure, same JSON Schema for message payloads, same components section for reuse. The team explicitly designed it to feel like OpenAPI's cousin so teams could adopt it without learning a new mental model. Message payloads reuse OpenAPI's schema language directly, which means schemas can move between the two specs without translation.
Where AsyncAPI stops: it describes the interface, not the delivery guarantees. If your webhook needs signed payloads, idempotency keys, and exponential backoff, AsyncAPI documents what the message looks like but doesn't hold the receiver accountable to processing it correctly. Those are runtime concerns — see webhook reliability patterns for what needs to sit alongside the spec.
Tooling is thinner than OpenAPI's but growing. There's a generator for code and docs, a studio for editing, and support in several major API management platforms. It's not yet the reflex the way OpenAPI is.
One detail worth calling out: both specs describe the interface, not the runtime. Neither one enforces retries, idempotency, ordering, or delivery guarantees. Those live in your implementation. What the specs do is document the contract clearly enough that both sides can build against it.
On schemas the two are effectively interchangeable. If you've defined a Customer schema in OpenAPI, you can $ref it from AsyncAPI, or vice versa. Keeping schemas in a shared components file is the cleanest way to avoid drift when both specs describe overlapping domain objects.
OpenAPI is the right answer when the interaction is synchronous and the client is doing the asking. That covers most of what SaaS platforms expose:
It's also the right choice when you need mature tooling. If you're generating SDKs in five languages, running spec-first mocks in CI, or feeding your API into an agent tool registry, OpenAPI is what those tools expect. Trying to force an event-driven pattern into OpenAPI's webhook object works for documentation but not much else — you lose the tooling advantage that was the reason to pick it in the first place.
A nuance: OpenAPI's webhooks object is fine when you're describing outbound HTTP callbacks that a caller has subscribed to as part of a synchronous flow — think Stripe's webhook events. If your event surface is a small side channel to an otherwise HTTP-shaped API, OpenAPI's webhooks object is probably enough. If events are a first-class part of the platform, they aren't.
AsyncAPI is the right answer when the interaction is asynchronous, the server (or a broker) initiates, and the caller is a receiver rather than a requester. Concretely:
It's also the right choice when you want the event surface to be a first-class documented product, not an appendix to the REST docs. Teams that treat webhooks as a serious integration surface — with catalogues, subscription management, and versioned payloads — get real leverage from AsyncAPI. Once you're describing 20+ event types across multiple channels, OpenAPI's webhooks object becomes a maintenance burden rather than a shortcut.
AsyncAPI also fits better when your platform has multiple event transports. If some events flow over webhooks, some over Kafka, and some over WebSockets, one AsyncAPI document can describe all three consistently. OpenAPI can't.
Most of the specification debate assumes the spec is the finish line — write it, publish it, and consumers will do the rest. When the consumer is an AI agent, that assumption doesn't hold. Agents don't read documentation portals. They call tools, and tools have to be generated, kept current, and executed with real user identity.
This is where the tools layer sits. Pontil generates agent tools from the APIs you already have — whether the interaction is synchronous (described by OpenAPI) or event-driven (described by AsyncAPI). The tool contract is derived from your existing spec, the runtime executes as the authenticated user, and maintenance stays aligned with your SDLC so the tools don't drift when the underlying API changes.
The short version: keep OpenAPI where OpenAPI fits, keep AsyncAPI where AsyncAPI fits, and use the tools layer to make either surface usable by agents. See what Tools-as-a-Service is for how the layer sits alongside your existing specs.
For most SaaS platforms with a REST API and a serious webhook surface: use both. Keep OpenAPI for the request-response API and AsyncAPI for the event surface, share schemas between them through a common components file, and treat the two documents as the two halves of your platform contract.
If the event surface is small — a handful of webhook types, no other transports — stay in OpenAPI and use the webhooks object. It's not perfect, but it saves you a second spec, a second toolchain, and a second review process. The cost of maintaining two specs is real.
If the event surface is large, multi-transport, or a real product in its own right, adopt AsyncAPI. The tooling gap is closing fast and the alternative — pretending event-driven APIs are just weird REST endpoints — leads to worse documentation and worse consumer experience over time.
The decision variable is honesty about what your platform actually is. Two shapes, two specs, one shared schema library. That's the setup that holds up.
Stay up to date on the ever changing agentic landscape.
GET STARTED
Start with a 30-minute discovery call
contactus@pontil.com
