Event-driven architectures and the AsyncAPI specification

I’m at the Barcelona airport. It’s summer and I’m finally going to visit my family in Badajoz after a long period. The queue at the security checkpoint looks endless but I have time. The phone rings. It’s my mom, she’s excited that I’m visiting and is giving me an update on how things are there now.

“Mom, I have to hang up the phone, it’s strictly forbidden in the security checkpoint. Chat soon.”

I hang up the phone and cross the security checkpoint. “What’s the gate?” I wonder. Look at the screens and try to find my flight: Ibiza, Madrid, Rome, aha! Badajoz! It’s gate C64. I head to the gate while taking the opportunity to reply to some messages.

Suddenly, I get a push notification on my phone: the gate has changed. It’s now C32. I look at the screens and, indeed, it’s different now. Instantly, a message on the public address (PA) system sounds: “Attention, passengers for the flight Iberia 8312 destination Badajoz, please go to gate C32.” Before the message could finish, I get another notification on my phone. This time is an email. Guess what? Exactly, the gate has changed.

I’m fascinated. Such a choreography! If you know me, you already know that event-driven systems are my passion. To the point that, during the flight, I opened my laptop and started drafting the way I imagined it works. Yes, when there’s no internet, imagination flies.

This is how I imagined the communication between the airline and the airport. The airline pushes a message to the broker on the “ibe/8312/updates” channel. The airport backend is subscribed to the same channel and therefore receives the message. Simple but powerful. The airport has no knowledge about the airline backend and the same in the opposite direction, the airline has no knowledge about the airport backend.

Now the airport backend can update the screens and trigger a PA message. But there’s more! I also received an email and a push notification on my phone so here’s how the diagram looks now:

The Gate Manager Service pushes a message to the broker and, along with the airport backend, the Notifications Service receives it, and sends an email and a push notification to all the users potentially affected by the change. Beautiful.

My next question was — inevitably — how do you describe all this with AsyncAPI and RAML? Hands on!

Let’s start by defining the data these services are exchanging. This is how I imagine a simplified version of it:

{
  "flight": {
    "origin": "BCN",
    "destination": "BDJ",
    “code”: “IBE8312”
  },
  “gate”: {
    “current”: “C32”,
    “previous”: “C64”
  },
  "timestamp": 2019-08-21T16:41:41.090Z
}

Using RAML data types, this could be defined as follows:

# airline-update.yaml
type: object
properties:
  flight:
    type: object
    properties:
      origin: string
      destination: string
      code: string
  gate:
    type: object
    properties:
      current: string
      previous: string
  timestamp: datetime

And this is how the AsyncAPI for the Gate Manager Service would look:

asyncapi: 2.0.0
info:
  title: Gate Manager Service
  version: 1.0.0
 
servers:
  airportBroker:
    url: broker.airport.com
    protocol: amqp
 
channels:
  /{airlineCode}/{flightCode}/updates:
    parameters:
      airlineCode:
        schema:
          type: string
      flightCode:
        location: $message.payload#/flight/code
        schema:
          type: string
    subscribe:
      message:
        schemaFormat: 'application/vnd.mulesoft.raml;version=1.0.0'
        payload:
          $ref: 'airline-update.yaml'

Since this is a simplified example where we only have one channel and message type, I’m avoiding defining the rest of the services API here. They would all look the same except for the “info” section and the operation verb, i.e., it would be “publish” instead of “subscribe.”

It was fun trying to imagine how these things work internally. I’m very happy to see how technologies like AsyncAPI and RAML are coming together to create better ways to define asynchronous communication patterns. They will have a huge impact on the Internet of Things industry and will enable architects to build faster and more reliable application networks. And, last but not least, it makes my mom happier that I haven’t missed my flight.

Have a safe flight.

To see more APIs in action, check out these API use cases.