AsyncAPI

Introduction

AsyncAPI is an open-source specification designed to standardize and simplify the development of Event-Driven Architectures (EDAs). It provides a framework for defining asynchronous API interfaces, thereby fostering a robust tooling ecosystem for EDAs. Its application ranges from automating documentation and code generation of event-driven services to establishing standards for events and enhancing governance of asynchronous APIs. AsyncAPI is not only designed for Event-Driven Architectures (EDAs), but it is also applicable to REST APIs. This makes it a comprehensive specification that encompasses the functionality of OpenAPI. It provides a standardized framework for defining interfaces of both asynchronous and synchronous APIs, thereby enhancing the governance and tooling ecosystem of APIs in general. Whether it’s REST APIs or event-driven services, AsyncAPI serves as a valuable resource for automating documentation, code generation, and establishing solid standards.

Features

  • Interface Definition: AsyncAPI facilitates the definition of interfaces for asynchronous APIs. It is protocol-agnostic, thereby supporting any communication protocol.

  • Documentation Generation: AsyncAPI provides the capability to generate documentation at various levels - build, server, and client. This enhances the understanding and usability of the APIs.

  • Code Generation: AsyncAPI supports the generation of code (including TypeScript, Java, C#, etc.) from AsyncAPI files. This feature accelerates the development process and ensures consistency across implementations.

  • Standardized Interface: AsyncAPI provides a standardized interface for defining asynchronous APIs1. It follows the same base syntax as OpenAPI to ensure consistency and compatibility2.

  • REST API Support: AsyncAPI extends its support to REST APIs, thereby encompassing the functionality of OpenAPI. It provides a standardized framework for defining interfaces of both asynchronous and synchronous APIs.

  • Innovation: AsyncAPI is the only specification that caters to the messaging needs in event-driven architecture.

  • Interactive API Explorer: While the AsyncAPI specification itself does not provide an interactive API explorer, there are tools in the AsyncAPI ecosystem that offer this functionality.

  • Validation and Testing Tools: While the AsyncAPI specification itself does not include tools for validating and testing API requests and responses, there are tools in the AsyncAPI ecosystem that offer this functionality.

Place in architecture

Our AsyncAPI implementation defines the APIs to connect different machines and services in an event-driven architecture. It is integrated into our architecture to ensure standardized API definitions and seamless communication. Here is a simplified view of its place in our architecture:

+----------------------+
|      Frontend        |
+----------+-----------+
           |
           |
+----------v-----------+       +----------v-----------+
|     Backend Services | <-----|     aerOS AsyncAPI   |
+----------------------+       +----------+-----------+

User guide

This section will help users understand how to use AsyncAPI to document their event-driven applications.

Prerequisities

  • To use AsyncAPI for REST APIs: Basic understanding of RESTful APIs and HTTP methods.

  • To use AsyncAPI for event-driven architectures: Basic understanding of event-driven architectures and messaging protocols.

  • An active internet connection.

Installation

  1. To create an AsyncAPI Document: To create an AsyncAPI document, no installation is required. It is possible to use the AsyncAPI studio to create the documentation.To create an AsyncAPI document locally, it is recommended to use the AsyncAPI extension for Visual Code.

  2. To validate an AsyncAPI Document: To validate an AsyncAPI document, could be used the AsyncAPI validator.

  3. To generate code from an AsyncAPI Document: To generate code from an AsyncAPI document, the AsyncAPI Generator is used. The AsyncAPI Generator is a tool that can generate documentation, code, and more from AsyncAPI files.It could be installed using npm with the following command:

    npm install -g @asyncapi/cli

Generate Code

After installing the generator, it is possible to generate code from the AsyncAPI document. Here is an example command:

asyncapi generate fromTemplate [asyncapi-file.yaml] @asyncapi/html-template -o outputDirectory

Developer guide

This section is intended for developers who want to contribute to the AsyncAPI project or create their own event-driven applications using AsyncAPI. It provides an overview of the AsyncAPI specification, its structure, and how to create and validate AsyncAPI documents.

Structure of an AsyncAPI document

An AsyncAPI document is a JSON or YAML file that defines the structure of an asynchronous API. It consists of the following main sections:

  1. AsyncAPI Version: The version of the AsyncAPI specification used in the document.

  2. Info: General information about the API, such as title, version, and description.

  3. Servers: Information about the servers that host the API.

  4. Channels: Definitions of the channels through which messages are exchanged.

  5. Components: Reusable objects that can be referenced throughout the document.

  6. Operations: Definitions of the operations that can be performed on the API.

Create a new AsyncAPI document

To create a new AsyncAPI document, follow these steps:

  1. Create a new JSON or YAML file.

  2. Define the AsyncAPI version at the beginning of the file.

  3. Add the required sections (Info, Servers, Channels, Components, Operations) to the document.

  4. Populate each section with the necessary information.

Validate an AsyncAPI document

To validate an AsyncAPI document, you can use the AsyncAPI validator. The validator checks the document against the AsyncAPI schema and reports any errors or warnings.

Contributing to the AsyncAPI project

If you want to contribute to the AsyncAPI project, you can do so by:

  1. Filing an issue: If you encounter a bug or have a feature request, you can file an issue on the AsyncAPI GitHub repository.

  2. Submitting a pull request: If you want to contribute code to the project, you can submit a pull request on the AsyncAPI GitHub repository.

Resources