Asynchronous enterprise architecture design using AsyncAPI

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.