Twitter | LinkedIn | YouTube | Instagram
If you’re working with event-driven applications, chances are you’ve heard of AsyncAPI. AsyncAPI is the standard specification for defining asynchronous APIs, just like OpenAPI is the standard specification for defining HTTP APIs.
](https://res.cloudinary.com/practicaldev/image/fetch/s--c87Sr9O9--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_66%2Cw_800/https://cdn-images-1.medium.com/max/2000/1%2A-31yzZKhJVtqYqFSALNLyw.gif)
Before AsyncAPI, there was no standard way to document event-driven architectures. This made it challenging for developers to understand and use these systems consistently. Therefore, in this story, we will see how we can get started with AsyncAPI and document our EDA applications.
Defining our specifications
AsyncAPI Version
We will start our specs by specifying the version of AsyncAPI we’re using. By the date I’m writing this article, it is 3.0.0:
asyncapi: 3.0.0
Service Information
What system is this documentation for? What is this system responsible for? In this part of our definition, we will specify the information regarding our service:
info:
title: Airplane Booking System
version: '1.0.0'
description: This API handles events related to booking flights.
Servers
What servers can I use to communicate with this system? What protocol do they use?
servers:
production:
url: localhost:9092
protocol: kafka
description: Apache Kafka broker - Production
local:
url: localhost:9092
protocol: kafka
description: Apache Kafka broker - Local Development
Channels
Message Brokers name their channels differently. In Kafka, they are topics. In RabbitMQ, they are exchanges or queues. What are the ones defined in our system? This is the section to define them.
channels:
flight/booked:
address: flight/booked
messages:
subscribe.message:
$ref: '#/components/messages/FlightBookedEvent'
description: Topic for flight booked events
flight/searched:
address: flight/searched
messages:
publish.message:
$ref: '#/components/messages/FlightSearchedEvent'
description: Topic for flight searched events
Operations
To interact with our channels, we need operations. Sometimes we will be publishing, sometimes we will be subscribing. What are the possibilities and their definitions?
operations:
flight/booked.subscribe:
action: send
channel:
$ref: '#/channels/flight~1booked'
messages:
- $ref: '#/channels/flight~1booked/messages/subscribe.message'
flight/searched.publish:
action: receive
channel:
$ref: '#/channels/flight~1searched'
messages:
- $ref: '#/channels/flight~1searched/messages/publish.message'
Allowed values are send and receive. Use send when it’s expected that the application will send a message to the given channel, and receive when the application should expect to receive messages from the given channel.
Components
The components section is a reusable and centralized place for defining various elements that can be referenced elsewhere in the document. It helps in avoiding duplication. In this example, we will only define two messages: FlightBookedEvent and FlightSearchedEvent.
components:
messages:
FlightBookedEvent:
name: FlightBookedEvent
title: Flight Booked Event
summary: Inform about a newly booked flight
payload:
type: object
properties:
userId:
type: string
format: uuid
flightId:
type: string
format: uuid
timestamp:
type: string
format: date-time
FlightSearchedEvent:
name: FlightSearchedEvent
title: Flight Searched Event
summary: Event triggered when a user searches for flights
payload:
type: object
properties:
userId:
type: string
format: uuid
description: The unique identifier of the user who made the search
searchParameters:
type: object
properties:
departureLocation:
type: string
description: IATA code for the departure airport
arrivalLocation:
type: string
description: IATA code for the arrival airport
departureDate:
type: string
format: date
description: The date of departure
returnDate:
type: string
format: date
description: The date of return (for round trips)
numberOfPassengers:
type: integer
description: The number of passengers
timestamp:
type: string
format: date-time
description: The time at which the search was performed
AsyncAPI Studio
AsyncAPI offers a free online studio we can use for editing, validating and visualizing our specs. Let’s use it to see if our specs are valid and how they would look when generated. You can click here to access the studio with the YAML file above pre-loaded on it.
Information & Available Servers
Operations
The first one is our SEND flight/booked operation. This means that other systems can subscribe to the flight/book topic. It has a short description (Topic for flight booked events), an operation ID and the servers on which it’s available.
At the bottom, we have which kind of message is accepted. In this case, it’s a Flight Booked Event. We can open the payload and see the specs of this message:
Or even check the example of the payload in JSON format:
Neat, right? Now, we can share our specs with our colleagues and let them know how they can easily interact with our systems.
In the next stories, I want to talk about AsyncAPI Generators. Tools that not only can be used for generating visualizations of our specs but also to generate code to be used in our applications based on our definitions!
Stay Curious!
Contribute
Writing takes time and effort. I love writing and sharing knowledge, but I also have bills to pay. If you like my work, please, consider donating through Buy Me a Coffee: https://www.buymeacoffee.com/RaphaelDeLio
Or by sending me BitCoin: 1HjG7pmghg3Z8RATH4aiUWr156BGafJ6Zw
Follow Me on Social Media
Stay connected and dive deeper into the world of documentation with me! Follow my journey across all major social platforms for exclusive content, tips, and discussions.
Top comments (0)