Async API is a way to describe event-driven APIs

Last Updated on 14/02/2022 by Patryk Bandurski

We are used to designing and exposing REST APIs using Design Center and Anypoint Exchange. MuleSoft is one of the leading middleware vendors that introduced the complete design life cycle. It helped a lot as the majority of the APIs are RESTs. On the other hand, we have event-driven APIs using queues, streams, sockets. So far, we did not have a consistent way to publish such APIs. Fortunately, MuleSoft is evolving, some time ago was added support for Async API in Design Center and Anypoint Exchange. Today I focus on the advantages of the Async API solution and a brief introduction to it.

What is Async API?

Async API is based on an Open API specification that defines interfaces for asynchronous APIs. The specification is protocol-agnostic so that you can work with Web Sockets, Kafka, HTTP streams, etc.

You can find complete documentation on the AsyncAPI web page. I encourage you to visit the page. You can play with the examples online and read the docs.

Advantages of Async API

• Simillar to Open API and RAML specifications
• Known specification
• Human readable
• Machine readable
• Protocol-agnostic (amqp, amqps, http, https, ibmmq, jms, kafka, kafka-secure, anypointmq, mqtt, secure-mqtt, solace, stomp, stomps, ws, wss, mercure)
• Support in Design Center and Anypoint Exchange

Example Async API for Payment Service

AsyncAPI has easily understood sections. In my example below, I have

• info (line 2) with basic descriptive information about my API
• servers (line 6) with server details to use by consumers/publishers
• channels (line 15) with queues/topics exposed by API
• components (line 29) with data types, security schemats etc

asyncapi: 2.0.0
info:
  title: Payment Service
  version: v1
  description: This service is in charge of processing payments
servers:
  test:
    url: test-broker.ambassadorpatryk.com
    protocol: jms
    description: This is JMS broker dedicated to test environments such as DEV/SIT
  prod:
    url: broker.ambassadorpatryk.com
    protocol: jms
    description: This is JMS broker dedicated to production
channels:
  payment/failed:
    subscribe:
      message:
        $ref: '#/components/messages/PaymentFailed'
  payment/approved:
    subscribe:
      message:
        $ref: '#/components/messages/PaymentApproved'
  payment:
    publish:
      summary: Create new payment
      message:
        $ref: '#/components/messages/Payment'
components:
  messages:
    Payment:
      payload:
        type: object
        properties:
          paymentId:
            type: string
            description: Payment ID
          amount:
            type: number
            description: Payment amount
          description:
            type: string
    PaymentApproved:
      payload:
        type: object
        properties:
          paymentId:
            type: string
            description: Payment ID
    PaymentFailed:
      payload:
        type: object
        properties:
          paymentId:
            type: string
            description: Payment ID
          reason:
            type: string
            description: Payment failure resaon

Payment Service is exposing three queues. In the servers‘ part, you can see connectivity details for test and prod environments. In the channels section, we have

• payment/failed – subscribe – this is a queue that user can subscribe to, to receive event notifications about failed payments
• payment/approved – subscribe – this is a queue that user can subscribe to, to receive event notification about approved payments
• payment – publish – this is queue that user can push message to initiate payment process

With each channel, we have associated data type like PaymentApproved. It gives consumers clear information on what structure is expected.

Anypoint Platform

MuleSoft added support to design Async API in Design Center and publish it to Anypoint Exchange. Experience is very similar to working with RAML specifications. You only need to pick New AsyncAPI from the drop-down while creating a new Project in Design Center.

Our Application Network can grow even bigger by introducing event-driven APIs. It is consistent with the current approach, so the users familiar with REST APIs on Anypoint Exchange will easily understand event-driver APIs.

In my opinion, this is another next step that I appreciate. I hope that MuleSoft will develop this feature even more and include something of Router, and enable code scaffolding like with the RAML specification. I keep thumbs up.

Summary

Async API is a specification based on Open API but dedicated to describing event-driven APIs. As a result, the learning curve is lower for people having experience with either RAML or Open API specification. You can start nearly straight away writing your own Async APIs.

Anypoint Platform support is limited for now. However, you can create Async API in Design Center and publish it on Anypoint Exchange. I see enormous potential in this, and I think we can expect further development and features that MuleSoft will provide.