The AsyncAPI Specification(A2S)
Credit
A portion of this content is derived from the excellent work of the OpenAPI Initiative team.
AsyncAPI 3.0.0
Within this document, the terms “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted in accordance with RFC 2119 regulations.
The Apache Licence, Version 2.0 governs the use of the AsyncAPI Specification.
Overview
A project called AsyncAPI Specification aims to provide machine-readable descriptions of message-driven APIs. You can use it for APIs that operate over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc.) because it is protocol-agnostic.
A set of attributes that can be used in an AsyncAPI document to describe an application’s API is defined by the AsyncAPI Specification. The document is usually a single main document that contains the API description; it may refer to other files for more information or shared fields.
The actions that an application takes SHOULD be detailed in the AsyncAPI specification.
It indicates that messages from the userSignedUp channel will be received by the application.
Software topology, architecture, or pattern of any type is not assumed by the AsyncAPI definition. As a result, a server could be any type of computer programme that can send and/or receive data, including message brokers and web servers. But AsyncAPI has a feature called “bindings” that tries to assist with more detailed protocol details.
Deriving a receiver AsyncAPI document from a sender document, or the other way around, is NOT SUGGESTED. It is not guaranteed that an application sending messages will utilise the same channel that another application is using to receive them. Additionally, several fields in the document, such as the operation’s id, description, and summary, may cease to make sense.
By swapping out receive for send,IBM cannot presume that an opposing application exists automatically:
In addition to the problems listed above, there might be other configurations of the infrastructure that are not included here. A system might, for example, utilise one read-only channel for messages, another for sending them, and a middleman process to forward messages between the channels.
Definitions
Server
A message broker that can send and/or receive messages between a sender and a recipient MAY be a server. A server could be a WebSocket API service that allows message-driven server-to-server or browser-to-server communication.
Application
Any type of computer programme, or collection of them, is called an application. A sender, a recipient, or both MUST be involved. An application could be a message broker, microservice, mainframe process, Internet of Things device (sensor), etc. Any number of programming languages may be used to create an application, provided that they support the chosen protocol. To connect and send messages, an application MUST also use a protocol that the server supports.
Sender
An application that sends messages to channels is called a sender. Senders may choose to send to more than one channel, based on the use-case pattern, protocol, and server.
Receiver
An application that receives messages from channels is called a receiver. Recipients may get data from various channels, contingent upon the server, protocol, and use-case design. A message that is received MAY be forwarded again by the recipient unaltered. Recipients MAY respond to the communication by acting as consumers. It is possible for a receiver to function as a processor, combining several messages into one and sending it.
Message
The method by which data is transferred across a channel between servers and applications is called a message. Both headers and a payload are possible components of a message. It is possible for the headers to be separated between header attributes defined by the application and protocol-defined headers, which can serve as supporting metadata. The application-defined data, which must be serialised into a format (JSON, XML, Avro, binary, etc.), is contained in the payload. A message can handle various interaction patterns, including event, command, request, and response, because it is a generic mechanism.
Channel
A channel is an addressable element that the server provides for message organisation. Applications that are senders send messages to channels, and applications that are receivers receive messages from channels. Multiple channel instances MAY be supported by servers, enabling messages with various content types to be addressed to various channels. Protocol-defined headers MAY allow the channel to be included in the message, depending on how the server is implemented.
Protocol
The method (wireline protocol or API) by which messages are transferred between the application and the channel is called a protocol. Mercure, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, and Pulsar are a few examples of protocols.
Bindings
A method for defining protocol-specific data is called a “binding” (also known as “protocol binding”). As a result, a protocol binding MUST only define data related to the protocol.
Specifications
Format
The files that follow the JSON standards and describe the message-driven API in line with the AsyncAPI Specification are represented as JSON objects. An A2S (AsyncAPI Specification) file can also be represented in YAML, which is a superset of JSON.
When a field is said to have an array value, for instance, the JSON array format is employed:
Although the API uses JSON to describe itself, the API does not require JSON input or output.
The specification uses case sensitivity for all field names.
Two kinds of fields are exposed by the schema. Patterned fields specify a regex pattern for the field name, whereas Fixed fields have a specified name. As long as each occurrence of a patterned field has its own name, they can appear more than once.
YAML version 1.2 is advised coupled with a few further restrictions to maintain the ability to round-trip between YAML and JSON formats:
- Only tags that are permitted by the JSON Schema standard may be used.
- The YAML Failsafe schema guideline stipulates that keys used in YAML maps MUST be restricted to a scalar string.
File Organisation
An AsyncAPI document MAY consist of a single document or, at the author’s option, be composed of several related portions. The latter scenario makes use of Reference Objects.
It’s crucial to remember that, aside from the Components Object, everything defined in an AsyncAPI document MUST be used by the implemented Application. Every definition contained within the Components Object designates a resource that the implemented Application MAY or MAY NOT use.
Asyncapi.json or asyncapi.yaml is the standard name for the AsyncAPI Specification (A2S) file.
URLs that are absolute
RFC3986, section 4.3 defines all characteristics that are absolute URLs, unless otherwise noted.
Schema
AsyncAPI Object
The API specification’s root document object is this one. It is a single document that includes both the API declaration and resource listing.
