AsyncAPI for documentation and validation of event-driven architecture
Tags: asyncapi, opensource, kafka, microservices
Published: 2020-02-17 11:54:04



In this blog post, you’ll read about what is [AsyncAPI](https://asyncapi.io/) and how at relayr we use it for validation of documentation of messaging between dozens of Node.js services.

# OpenAPI and Swagger
Let’s first talk a little about OpenAPI and [Swagger](https://swagger.io/). The Swagger specification was founded back in 2010 as a design specification for RESTful APIs. It got a lot of attention from the whole development community and within a few years, it was being used by many big companies. In 2015, the Swagger specification was donated to Linux Foundation and renamed to OpenAPI and is now managed by [OpenAPI Initiative](https://www.openapis.org/).

# AsyncAPI
The Swagger specification was created in 2010. Nowadays, more and more companies are moving towards event-driven/message-driven and microservices architecture where multiple services communicate with each other over some messaging protocol, such as [Kafka](https://kafka.apache.org/intro), [RabbitMQ](https://www.rabbitmq.com/) or even web sockets.

This brought the need to have a specification for messaging between services. The AsyncAPI specification solves this problem. It lets you define the schema for messages between services with any kind of protocol. I once called it "Swagger for Kafka" 😄. [@fmvilas](https://twitter.com/fmvilas) started the project in 2017 at Hitch and now works 24/7 for it 💪. We have around 16 backers on [OpenCollective](https://opencollective.com/asyncapi) 🎉.

Let’s now talk about the advantages of AsyncAPI!


## A contract between multiple parties
AsyncAPI provides a contract for communication between consumers and producers. In our case, there could be multiple consumers and producers so it’s a contract between all of them. It tells what should be included in the payload when a service produces a message and also tells the consumer about the properties in the message.

## Understandable by humans and machines
As AsyncAPI is a schema definition, it is understandable and readable by both machines and humans. The schema can be written in YAML or JSON format which can be easily used with Node.js. It also provides a nice HTML or Markdown document which is human readable.

## Testing and validation
AsyncAPI can be used for testing and validation of the payload. At relayr, we wrote the validation library asyncapi-validator which I describe in detail in the [Architecture at relayr](#Architecture-at-relayr) section of this article.

## Documentation
One other big benefit of using AsyncAPI is that it provides nice documentation for all the messages in-between your services. You can tag them as you like and also define custom properties.

![AsyncAPI Playground for schema](https://engineering.relayr.io/static/aadd9a9068504ee5cec8c74b4aedf9f0/22a9b/playground-example.png "AsyncAPI Playground for schema")
You can use the AsyncAPI Playground here: [playground.asyncapi.io](playground.asyncapi.io)

In the above example, I have defined a simple `userCreated` event. It has the three properties `id`, `userName` and `role`, where id is the required field. The schema definition is almost the same as the Swagger file. In the screenshot, you can see the generated example and schema view, which is easily readable and understandable.

# Architecture at relayr
![relayr architecture](https://engineering.relayr.io/static/89270592a8ed4b7fc50291677ef6ab06/07004/relayr-architecture.png "relayr architecture")

At relayr, we have multiple services running with Node.js and communicating using Kafka. We receive data from various client devices through MQTT. A Node.js service receives all these messages and then publishes relative Kafka messages. We wanted to validate that clients are sending the right payload, so we wrote an AsyncAPI schema for MQTT messages and also one for Kafka messages.

# asyncapi-validator
To validate incoming MQTT messages, I wrote the [asyncapi-validator](https://www.npmjs.com/package/asyncapi-validator) with which you can validate any message against its AsyncAPI schema definition. First, you have to load the AsyncAPI schema definition using the `fromSource` method and then you can validate any message with its key and payload using the validate method. Here is an example of validation for the schema we defined earlier for the `userCreated` event.

![validator example](https://engineering.relayr.io/static/431b41d7c086f8670188ecb5bcc88aed/ba419/validator-example.png "validator example")
This validation will give the below error because `id` should be a UUID and `userName` should be an email.

![error example](https://engineering.relayr.io/static/26562b1c6f3d31f9c25813af83660df1/8a479/error-example.png "error example")
We added the asyncapi-validator where we receive messages from the MQTT broker. If the messages pass the validation, we let them through. If they fail, we generate related error messages back to the device, so that the client can fix the payload. We also log the failures in our system for debugging.

# AsyncAPI v2.0
I started working with the AsyncAPI core team. We recently released version 2.0 of the AsyncAPI schema which has a lot of improvements. We are looking for more contributors. There is a lot of development going on around the schema definition and tooling. For details, check [asyncapi.io](asyncapi.io) or join our [slack](https://asyncapi.com/slack-invite).

The asyncapi-validator is also open source: [npmjs.com/package/asyncapi-validator](https://www.npmjs.com/package/asyncapi-validator). If you have any questions, feel free to reach out to me on twitter: [@waledashraf01](https://twitter.com/WaleedAshraf01)