Asynchronous architectures have a lot to offer designers at the enterprise level. Unlike synchronous architectures, which can be hard to scale and run the risk of performance bottlenecks due to long-running request/response sessions, asynchronous architectures benefit from being flexible and fast.
This isn't to say that asynchronous architectures don't have tradeoffs. They are, by nature, more challenging to comprehend than their synchronous counterparts. And, despite having been around a while, up until recently, there really hasn't been a lot of standardization around the way asynchronous messages are defined, published, and consumed within the given application. An enterprise-level asynchronous application can have hundreds of events generated during its operation. Each event can have one or more messages generated when an event fires. Keeping track of it all can be a significant chore when there's no standard format in play. For many companies, each project can be an adventure in reinventing the wheel.
Fortunately, the industry has been well aware of the need to standardize asynchronous messaging formats for a while. As a result, some interesting specifications have appeared on the horizon. The AsyncAPI project publishes one such specification. The project's sponsors include Salesforce, Slack, Mulesoft, and SAP, to name a few. This level of support alone makes the AsyncAPI well worth knowing.
In this article, I'm going to give a very high-level overview of the specification. Then, I am going to provide a discussion about the code generation and message validation features the project offers.
Let's start with the specification.
Understanding the AsyncAPI specification
The AsyncAPI specification allows API designers to have a conventional way to describe the essential organization and data structures for a message-driven, asynchronous API. You use AsyncAPI to define the URLs that are associated with the API. Within the AsyncAPI framework, a URL maps to a channel. You can think of a channel as a mailbox for messages. Messages are sent into the mailbox by publishing into the API. Consumers get a message from the mailbox by subscribing to it. Also, you'll use the specification to define the structure of the messages that the given channel will support.
Listing 1 below shows an example of a simple AsyncAPI specification.
1 asyncapi: 2.0.0
2 info:
3 title: Account Service
4 version: 1.0.0
5 description: This service is in charge of processing user signups
6 channels:
7 user/signedup:
8 subscribe:
9 message:
10 $ref: '#/components/messages/UserSignedUp'
11 components:
12 messages:
13 UserSignedUp:
14 payload:
15 type: object
16 properties:
17 displayName:
18 type: string
19 description: Name of the user
20 email:
21 type: string
22 format: email
23 description: Email of the user
Listing 1: A basic AsyncAPI specification
Notice in Listing 1 above that the AsyncAPI specification describes an API with the title, Account Service
(Line 3). Account Service
has a single channel, user/signedup
(Line 7), and when interested parties subscribe to that channel, those parties will receive a UserSignedUp
message (Line 13). The UserSignedUp
message has two properties, displayName
(Line 17) and email
(Line 20). Both are of data type, string
.
Listing 1 above is about as lean as you can get when using AsyncAPI to specify an asynchronous application programming interface. It shows a way to get messages out of the API. Also, the example describes the exact format of the message being emitted, data type included.
Should API designers want to describe how to send messages into the API, they would add a publish
attribute to the specification's YAML file. Listing 2 below shows the Account Service
API with a new publish channel named user/signingup
added at Line 11.
1 asyncapi: 2.0.0
2 info:
3 title: Account Service
4 version: 1.0.0
5 description: This service is in charge of processing user signups
6 channels:
7 user/signedup:
8 subscribe:
9 message:
10 $ref: '#/components/messages/UserSignedUp'
11 user/signingup:
12 publish:
13 message:
14 $ref: '#/components/messages/UserSignedUp'
15 components:
16 messages:
17 UserSignedUp:
18 payload:
19 type: object
20 properties:
21 displayName:
22 type: string
23 description: Name of the user
24 email:
25 type: string
26 format: email
27 description: Email of the user
Listing 2: The Account Service API with a publish channel, user/signingup, added
You'll notice that in Listing 2 above, both the subscribe
and publish
verbs use the same message type, UserSignedUp
. This is OK for this illustration, but in the real world, the messages used by the publish
and subscribe
verbs for a common process, for example, signing up to a website, will be different.
Check out AsyncAPI Playground
The AsyncAPI project publishes a tool named AsyncAPI Playground that provides linting and real-time documentation rendering of the specification you're writing. The figure below shows the AsyncAPI specification displayed above in Listing 1 in the Playground. You can view the actual specification in the AsyncAPI Playground by going here.
The important thing to know about the AsyncAPI project is that it provides a way to define a message-based, asynchronous API in exacting detail. Once an API is defined using AsyncAPI, the API architect gives the spec to developers to code. There's not a lot of the back-and-forth and guesswork involved that tends to slow down application development. Thus, the inherent benefit of an accelerated development process. And when you take advantage of the project's code-generation tools, development activity can go even faster.
Code generation and message validation
The AsyncAPI project lists several tools that increase the speed and ease of developing an asynchronous API. One set of tools is the code generators.
The AsyncAPI code generators will consume the specification's YAML and emit boilerplate code in a variety of programming languages, such as Node.js, Python, and Java/Spring. Also, there are generators for creating an API's documentation in HTML or Markdown formats. (See Figure 2 below.)
In addition to the code generation tools, some projects are ancillary to AsyncAPI that provide message validation capabilities, for example, asyncapi-validator. (See Figure 3.)
Message validation
Also, the AsyncAPI project publishes a JavaScript parser that will transform a given specification in YAML or JSON into a set of programmable JavaScript objects.
Putting it all together
Having a standard format by which to specify an application programming interface (API) for an asynchronous system is a big step forward for enterprise architecture design and development. Having a single source of truth that provides a precise level of detail allows architects and developers to have a common reference point for creating industrial-strength systems quickly and, most importantly, accurately. All too often, the system envisioned in an architect's imagination gets lost in translation by the time a developer is realizing it all in code.
AsyncAPI has the detail and support necessary to make it a conventional standard by which asynchronous systems can be specified. As with any useful specification, there's a lot that needs to be learned. The devil really is in the details. Once you master the specification's format, however, you can use the code generation, parsing, and validation tools to accelerate the time it takes to get a powerful message-driven API into the hands of the consumer. As those of us on the terrain learned a long time ago, getting useful software out into the hands of consumers is what it's all about.
About the author
Bob Reselman is a nationally known software developer, system architect, industry analyst, and technical writer/journalist. Over a career that spans 30 years, Bob has worked for companies such as Gateway, Cap Gemini, The Los Angeles Weekly, Edmunds.com and the Academy of Recording Arts and Sciences, to name a few. He has held roles with significant responsibility, including but not limited to, Platform Architect (Consumer) at Gateway, Principal Consultant with Cap Gemini and CTO at the international trade finance company, ItFex.
More like this
Browse by channel
Automation
The latest on IT automation for tech, teams, and environments
Artificial intelligence
Updates on the platforms that free customers to run AI workloads anywhere
Open hybrid cloud
Explore how we build a more flexible future with hybrid cloud
Security
The latest on how we reduce risks across environments and technologies
Edge computing
Updates on the platforms that simplify operations at the edge
Infrastructure
The latest on the world’s leading enterprise Linux platform
Applications
Inside our solutions to the toughest application challenges
Original shows
Entertaining stories from the makers and leaders in enterprise tech
Products
- Red Hat Enterprise Linux
- Red Hat OpenShift
- Red Hat Ansible Automation Platform
- Cloud services
- See all products
Tools
- Training and certification
- My account
- Customer support
- Developer resources
- Find a partner
- Red Hat Ecosystem Catalog
- Red Hat value calculator
- Documentation
Try, buy, & sell
Communicate
About Red Hat
We’re the world’s leading provider of enterprise open source solutions—including Linux, cloud, container, and Kubernetes. We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.
Select a language
Red Hat legal and privacy links
- About Red Hat
- Jobs
- Events
- Locations
- Contact Red Hat
- Red Hat Blog
- Diversity, equity, and inclusion
- Cool Stuff Store
- Red Hat Summit