AsyncAPI and OpenAPI are different ways of defining application programming interfaces (APIs), also commonly known as API specs. Both API specs serve a crucial role in defining and governing distributed computing systems leveraging the concepts of request/reply RESTful interactions, event-driven architecture, microservices and Webhooks, but AsyncAPI and OpenAPI are used for different styles of integration, as seen here:
This post answers the following common questions about AsyncAPI vs OpenAPI and APIs in general…
Application programming interfaces, or simply “APIs”, are a key part of modern programming that make it easier to exchange information between applications. APIs tell you what kind of information and requests an application expects to receive, and what you can expect in a reply, without needing to know what the application does or how.
As long as the API doesn’t change, different teams can invoke the application’s functionality without worrying about the messy details underneath. Because of this, separate teams can work independently on implementations.
As APIs gained popularity, they began reaching across the boundaries of businesses. Companies like Twitter and Uber exposed their APIs to the world through API gateways, and began to consider APIs products in their own right.
APIs have been around for a while. For instance, the painful Simple Object Access Protocol (SOAP) used APIs in the early 2000s, but they really started getting interesting when representational state transfer (REST) came along. REST, which used the ubiquitous HTTP protocol, was lightweight and fun to work with.
There was no great way to tell people in your company or a partner what needed to be in REST requests, and what they could expect as a reply. Whether the request needed a PUT or a POST was a constant source of confusion, and without a standard way of describing REST APIs, you had to resort to emailing.
Something needed to happen. Swagger and WADL to the rescue! The goal of these competing standards was to standardize a way of documenting what a REST API looked like that was both readable by humans (somewhat, anyway) and could programmatically validate incoming requests and generate code.
Ultimately the Swagger Specification proved to be more popular and emerged as the de facto standard.
The Swagger specification was renamed OpenAPI in 2016 when the Linux Foundation acquired it from the fine folks at SmartBear. Somewhat confusingly, Swagger lives on as a toolset for creating and manipulating OpenAPI specs.
They are related but different. OpenAPI describes and documents how a REST API operates in a standard way so that it can be shared widely.
Microservices architecture was the new, cool kid on the street. Its purpose is to split up huge globs of code into tiny, manageable pieces, so different teams can work on them simultaneously.
If a company wants to create something new, it glues different combinations of microservices together using REST calls. This method for microservices architecture worked… to an extent. People eventually realized that REST wasn’t the best glue, and recognized the need for a new kind of glue that facilitated asynchronous communication.
Establishing asynchronous communication between microservices makes them more reliable, faster, easier to scale, and more agile to adopt. Here’s a great video explaining why.
The internet of things also changed things up. My coffee cup is connected to the Internet now. Which is fantastic. But internet connected gadgets like cars and stoves and refrigerators don’t always have solid internet connections. Again, asynchronous communication seemed like a better way to connect.
With asynchronous communication, if a device is inaccessible, the information can be stored until it comes back online. Asynchronous communication can also help handle the surge of data than can come from connected devices. For example, think about all the coffee mugs firing up at 7am in the morning…
You may be wondering why OpenAPI struggles with asynchronous APIs. Well, OpenAPI assumes two things:
As you can see here, that only covers 25% of the ways that APIs can be implemented.
Asynchronous communications do not satisfy those assumptions in numerous ways, but two stand out:
Without diving too deep, AsyncAPI adapts many of the core structures of OpenAPI to the asynchronous world. Rather than assuming that information flows in a request-reply style between a single client and server pair, messages are assigned to “channels” that many applications can send messages to, or receive messages from. If you want to learn more, check out the primer on the AsyncAPI website.
With the combination of OpenAPI and AsyncAPI, many more API possibilities are covered, as you can see in this diagram:
There’s no reason it can’t be, which is one of the reasons many companies are focusing more on evented API products, along the lines of more traditional API products. Companies like Slack are already letting outsiders use evented APIs.
One of the cool things about AsyncAPI is that you can use a variety of different protocols that are defined by “bindings”. Right now, there are AsyncAPI bindings for over a dozen protocols including Apache Kafka, AMQP, IBM MQ, MQTT, SNS, WebSockets, and JMS.
If you want to see examples of how AsyncAPI can help you create an asynchronous API, there’s a great series with WebSockets examples here, and you can check out this code generation example from Solace. If you’re looking for how to create an AsyncAPI API from scratch, the easiest way is with the AsyncAPI playground.
AsyncAPI and OpenAPI are now both part of the Linux Foundation, which means: