Skip to content

This repository contains information, references, and samples about AsyncAPI

License

Notifications You must be signed in to change notification settings

meteatamel/asyncapi-basics

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

41 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AsyncAPI Basics

AsyncAPI Logo

This repository contains information, references, and samples about AsyncAPI.

AsyncAPI: Why? What?

AsyncAPI is an open source initiative with the goal of making event-driven APIs as easy as REST APIs. Fundamentally, it is a specification to define an asynchronous APIs, similar to what OpenAPI (aka Swagger) does for REST APIs.

AsyncAPI also provides tools to visualize and validate AsyncAPI specs and generators to generate code from the spec in various languages and frameworks.

Specs and schemas

You can see all the previous and current specs of AsyncAPI. Specs for the latest and the previous versions:

You can also validate the AsyncAPI documents with the AsyncAPI JSON Schema definitions. Schemas:

AsyncAPI 2.6.0 vs 3.0.0

3.0.0 was released in December 2023 with breaking changes. These pages provide more context and help on how to migrate from 2.6.0:

Concepts

These are the main concepts in AsyncAPI:

  • Application: A producer or a consumer that support the selected protocol to exchange messages with the server.

  • Server: An infrastructure that receives messages and delivers them to those interested. They often store messages until delivered. Examples are Google Cloud, RabbitMQ, Apache Kafka, Solace, etc.

  • Channel: An addressable component created by the server to organize transmission of messages between producers and consumers. Channels can be defined as a topic, queue, routing key, path, or subject depending on the protocol used.

  • Protocol: How information is exchanged between applications and channels such as AMQP, HTTP, WebSocket, JMS, Kafka, MQTT etc.

  • Producer (Publisher): An application that sends messages to a channel.

  • Consumer (Subscriber): An application that consumes messages from a channel.

  • Message: Mechanism to exchange information between servers and applications via a channel serialized in the format specified by the protocol. It can support multiple patters such as event (to communicate that a fact has occurred), command (to instruct subscriber to do something), request or response.

  • Binding: Server, channel, operation, and messaging bindings allow protocol-specific information, e.g. Google Cloud Pub/Sub Server Binding, Google Cloud Pub/Sub Channel Binding, Google Cloud Pub/Sub Operation Binding, Google Cloud Pub/Sub Message Binding.

OpenAPI vs. AsyncAPI

If you're coming from OpenAPI and you want to see how it compares to AsyncAPI, here's a nice diagram from the AsyncAPI docs.

OpenAPI vs. AsyncAPI

How does an AsyncAPI spec look like?

hello-world1-2.6.yaml is the simplest AsyncAPI possible in 2.6.0. It's an application that has a single hello channel. Users can publish messages to this channel and the message payload is simply a string.

# The simplest AsyncAPI definition possible in 2.6.0
asyncapi: 2.6.0
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string

hello-world1-3.0.yaml is the simplest AsyncAPI possible in 3.0.0. It's an application that has a single hello channel. Server receive messages to this channel and the message payload is simply a string.

# The simplest AsyncAPI definition possible in 3.0.0
asyncapi: 3.0.0
info:
  title: Hello world application
  version: 0.1.0
channels:
  hello:
    address: hello
    messages:
      publish.message:
        payload:
          type: string
operations:
  hello.publish:
    action: receive
    channel:
      $ref: '#/channels/hello'
    messages:
      - $ref: '#/channels/hello/messages/publish.message'

hello-world2-2.6.yaml and hello-world2-3.0.yaml are more complicated AsyncAPI definitions with servers, channels, components and schemas.

Publish vs. Subscribe semantics in AsyncAPI 2.6.0

In a channel, you can have publish and subscribe operations. This can be confusing, depending on which perspective you're considering (server vs. user) and what you're comparing against (eg. WebSocket).

AsyncAPI Term WebSocket Term From Server Perspective From User Perspective
Publish Send The server receives the message The user publishes/sends the message to the server
Subscribe Receive The server publishes the message The user subscribes/receives the message from the server

It's most useful to think of publish and subscribe from user's perspective. You can read Demystifying the Semantics of Publish and Subscribe for more details.

Receive vs. Send semantics in AsyncAPI 3.0.0

In AsyncAPI 3.0.0, you have send and receive operations instead and it refers to the server sending and receiving messages.

Tools

These are some of the useful tools for AsyncAPI:

  • AsyncStudio: Browser based tool to author and visualize and validate AsyncAPI files.
  • AsyncAPI CLI: CLI based tool to work with AsyncAPI files.
  • AsyncAPI Generator: A number of code generators for various languages and frameworks.

AsyncStudio is especially useful tool to author, visualize and validate AsyncAPI files. Here's the previous sample visualized in AsyncStudio:

AsyncStudio

Samples

AsyncAPI has some basic samples in spec/examples folder.

More samples in this repo in samples folder:

  • hello-asyncapi - HelloWorld samples for AsyncAPI.
  • quickstart - Shows how to generate an AsyncAPI spec, validate it and generate code from it using AsyncAPI tools.
  • account-email-services - Show how to author an AsyncAPI spec for a simple 2 microservices architecture.
  • account-service-cloudevent - Shows AsyncAPI specs for a service that accepts CloudEvents in binary and structured formats.
  • google-pubsub - Shows AsyncAPI spec for Google Cloud Pub/Sub.

References

These are some references I found useful in my research:

About

This repository contains information, references, and samples about AsyncAPI

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published