Hackathon

Our Global Hackathon is on! Join us →

AsyncAPI Conference (Nov 16-18)

Coming from OpenAPI

Found an error? Have a suggestion?Edit this page on Github

On this page

If you're coming from OpenAPI, you must know that AsyncAPI started as an adaptation of the OpenAPI specification. We wanted to have as much compatibility as possible between the two so users could reuse parts in both.

You'll find lots of similarities between OpenAPI and AsyncAPI. Just bear in mind that in the world of event-driven architectures, you have more than one protocol and therefore some things are different. Check out the following comparison chart, inspired by Darrel Miller's blog post:

OpenAPI 3.0

Info
Hosts
Security
Paths
Path Item
Summary and description
Operation (GET, PUT, POST, etc.)
Request
Responses
Tags
External Docs
Components
Definitions
Responses
Parameters
Response Headers
Security Definitions
Callbacks
Links

AsyncAPI 2.0

Info
Servers (hosts + security)
Channel
Channel Item
Operation (Publish and Subscribe)
Summary, description, tags, etc.
Message
Headers
Payload
Id (application identifier)
Tags
External Docs
Components
Schemas
Messages
Security Schemes
Parameters
Correlation Ids
Operation Traits
Message Traits
Server Bindings
Channel Bindings
Operation Bindings
Message Bindings

Aside from structural differences you must know that:

  1. AsyncAPI is compatible with OpenAPI schemas.
  2. Message payload in AsyncAPI can be any value, not just an AsyncAPI/OpenAPI schema. For instance, it could be an Avro schema.
  3. AsyncAPI server object is almost identical to its OpenAPI counterpart with the exception that scheme has been renamed to protocol and AsyncAPI introduces a new property called protocolVersion.
  4. OpenAPI path parameters and AsyncAPI channel parameters are a bit different since AsyncAPI doesn't have the notion of "query" and "cookie", and header parameters can be defined in the message object. Therefore, AsyncAPI channel parameters are the equivalent of OpenAPI path parameters.

Conclusion

As you have seen above, OpenAPI and AsyncAPI are very similar. In a real-world environment, systems don't have just REST APIs or events but a mix of both. Most of the time, the information flowing in the events is very similar to the one the REST APIs have to handle in requests and responses; thus, being able to reuse schemas is a huge win.

Enough reading, it's time to get your hands dirty with some actual examples. Let's learn how to create an AsyncAPI document that defines a "Hello world" application.