The world of APIs is often one of competing standards, interests, and solutions. While we tend to talk about the API space as a cohesive community, the reality is that APIs on the internet encompasses something more universal.

In the API documentation space, this ultimately comes down to a question of consumption. Who is actually using the documentation? What purpose does that documentation serve? How does it drive the product and increase its value?

Today, we’re going to look at documentation solutions for two very broad types of APIs: OpenAPI and AsyncAPI. Both of these solutions generate machine-readable documentation, a concept that we will discuss shortly, but they do so for wildly different types of APIs.

Why Document?

Documentation is universal for technical projects. So much so that it is often seen as important as the code itself. API documentation is essentially a consumption, utilization, and contextualization bible: it serves the purpose of not only informing the end-user but contextualizing and explaining that information to make it useful for some application.

There are two core types of documentation. Human-readable documentation informs the end-user and explains the information in a method that can be easily consumed by a human being. This is the form of documentation that most people are likely familiar with. Such documentation is not solely technical. We often see user manuals and other help documentation in common retail products, software downloads, etc.

The opposite type of documentation is machine-readable. As the name suggests, it is solely concerned with providing technical documentation that can be parsed, understood, and utilized by machines. Unlike human-readable documentation, which is primarily used for base-level understanding and reference, machine-readable documentation is often used for ingesting and producing a byproduct or integration. This documentation can be used to develop new tools, render new data, or even develop shim layers to facilitate better inter-API communication.

As previously stated, both solutions below are machine-readable. What specifically they document, however, is where we see divergence.

OpenAPI

OpenAPI Specification can be used to secure and accelerate the API lifecycle.

OpenAPI Specification, known formerly as the Swagger, is a solution that produces machine-readable documentation for REST APIs. Initially developed in 2010, Swagger was later acquired in 2015 by SmartBear Software. As Swagger was developed and expanded, the Open API Initiative was launched to further develop and promote the Swagger toolset in an open format, supported by major industry players to ensure standardization and support. In 2016, Swagger was officially renamed to the OpenAPI Specification.

OpenAPI is language-agnostic and is used to automatically generate documentation for a wide set of functions, methods, parameters, models, and more. The main selling point behind OpenAPI is that, in unifying and standardizing the documentation in this way, the client libraries, source code, executables, and documentation are all natively synced, as the specification documentation itself is used to generate most of the rest.

Add on to this the declarative resource utilization, which means that the end-user does not need to have any knowledge of server implementation, resources, access to server code, etc. to understand and consume the services, and you’ve got a very strong solution for RESTful web services.

AsyncAPI

AsyncAPI started as a side-project at Hitch (API Changelog), and was later founded by Fran Méndez. The developers of AsyncAPI identified the lack of tooling in the message-driven space, and, when presented with a conversely abundant set of tools for HTTP APIs, decided that there was a missing piece of standardization in documentation specifications.

From this identified need, they started looking for a solution to the standardized message-based specification systems. They formulated a “theory of APIs” so to speak – essentially, with so many interacting API types like RESTful web services, GraphQL, and message-driven architectures, AsyncAPI would serve as a common unifying language for the diverse formats, protocols, and specifications, allowing for standardized communication in the message-driven system.

The support is ostensibly effective – by their own calculations, assuming that they create tooling for 6 programming languages, 4 schema formats, and 5 protocols, they would be able to generate 120 possible combinations in the message-driven space. That’s a significant number and one that certainly delivers on the standardized solution that was originally designed.

Differences

Ultimately, the two solutions here cover very separate sides of the same coin. REST APIs have a specific function and purpose, and as such, they require their own documentation methods and approaches. REST APIs have, amongst others, a great solution in the form of OpenAPI – a set of standardized documentation methods to enable tooling and interactivity.

Message-driven APIs are very different, however, and they need their own solution that covers the caveats and considerations intrinsic to message-driven architectures. For these APIs, there is AsyncAPI, which does functionally the same thing as OpenAPI, but with a message-driven focus. The tagline for AsyncAPI says it best – “REST APIs have OpenAPI. Messaging has AsyncAPI.”

It’s very important to understand that, while the two solutions have much in common, they are also wildly divergent. Yes, both OpenAPI and AsyncAPI enable a greater amount of cooperation and collaboration between different documented APIs, but OpenAPI is very much a solution for REST, and AsyncAPI is very much a solution for Message-driven architectures. They are entirely different realms, despite the similar-sounding names and similar-sounding purposes.

Conclusion

Ultimately, the issue here is one that is more of nomenclature than it is of function. AsyncAPI and OpenAPI sound very similar to the ear, and because of this, they tend to be placed into the same intellectual “bucket.” This is a poor way of looking at the solutions, however, as the divergent purposes paint a very striking picture of different form and function between the two.

Simply put, adopting AsyncAPI is a no-brainer for message-driven APIs, but the same can be said for OpenAPI for RESTful APIs – and conversely, there’s no reason for AsyncAPI to really come up in a conversation about RESTful APIs, or for OpenAPI to be discussed in the context of message-driven architectures.

We hope that this has cleared up some misconceptions around these two solutions. Let us know in the comments what you think, and whether or not this was helpful.