Learn how to put your digital team to work with MuleSoft for Agentforce.
Register now
Contact Us 1-800-596-4880
  1. Homepage
  2. Design Center
  3. Designing API Specs and Fragments

  4. AsyncAPI Specifications

AsyncAPI Specifications

You can create or import your AsyncAPI specifications in API Designer and then edit, document, and publish them.

AsyncAPI is a language that describes messaging interfaces. This open-source, industry-standard language is agnostic to any technology. To learn more, see the AsyncAPI documentationLeaving the Site.

AsyncAPI makes it easy to work with event-driven architecture by separating the API into three layers:

  • Events: Message or data to be shared with other services

  • Channels: Destination of the message to be sent or received

  • Transport: Technology that transports the message, such as RabbitMQ, Kafka, or Anypoint MQ

You can create or import an API specification in API Designer.

Create an AsyncAPI Specification in API Designer

To create an AsyncAPI specification in API Designer:

  1. In Design Center, click Create New.

  2. Select New AsyncAPI.

  3. In the New AsyncAPI dialog, name your project.

  4. Select the AsyncAPI language under Specification Language.

The text editor opens.

For more information about how to use API Designer, refer to Create an API Specification with the Text Editor.

Import AsyncAPI Specifications

To import AsyncAPI specifications from Anypoint Exchange or from your filesystem:

  1. Click the gear icon at the top right of the text editor.

  2. Select from the following options:

    • Select Import from Exchange to see the following lists:

      • API specifications that are available from the business organization that your user ID belongs to in Anypoint Platform

      • API specifications that are published by MuleSoft

    • Select Import to import an API specification from your local filesystem.

  3. As appropriate, continue to work with your AsyncAPI specification in API Designer:

    • Develop and edit AsyncAPI specifications.

    • View documentation that is included in AsyncAPI specifications.

    • Publish AsyncAPI specifications to Anypoint Exchange.

Example AsyncAPI 2.6 Specification

Following is an example that you can copy into API Designer to get started with event-driven APIs.

The following API specification example defines a typical event-driven process that uses Anypoint MQ and Kafka protocols. Sections in the example specification are:

  • AsyncAPI

    Identifies the API model as AsyncAPI and specifies the title and version of the API spec

  • Servers Defines message brokers that determine the connectors to use (indirectly) when publishing events or subscribing to events through operations in the AsyncAPI module:

    • AMQ-prod configures an Anypoint MQ Broker

    • Kafka-prod configures a locally hosted Kafka broker

  • Operation Defines the action that the application takes and whether the event is consumed or published

  • Channels Defines the bindings:

    • order-placed, order-cancelled, and order-confirmed configures Anypoint MQ channels for publishing and subscribing to orders

    • order-backordered configures a Kafka channel for publishing and subscribing to backorders

  • Components

    Defines the structure of messages for the different types of orders, which include OrderPlaced, OrderCancelled, OrderConfirmed, and BackOrder

To try the example, create a new AsyncAPI specification in Design Center and copy the following code directly into API Designer:

Example AsyncAPI 2.6.0 Specification (Inline Avro)

If you created an AsyncAPI specification project, you can replace the initial API specification with following example code to test inlining the API specification fragments:

Example AsyncAPI Specification Fragment (Avro Schema)

If you created an Avro Schema fragment, you can replace the initial API fragment with following example code:

{
  "name": "AmericanFlightDataType",
  "type": "record",
  "fields": [
    {"name": "ID", "type": "int", "default": 1},
    {"name": "code", "type": "string", "default": "ER38sd"},
    {"name": "price", "type": "int", "default": 400},
    {"name": "departureDate", "type": "string", "default": "2017/07/26"},
    {"name": "origin", "type": "string", "default": "CLE"},
    {"name": "destination", "type": "string", "default": "SFO"},
    {"name": "emptySeats", "type": "int", "default": 0},
    {
      "name": "plane",
      "type": {
        "name": "Plane",
        "type": "record",
        "fields": [
          {"name": "type", "type": "string"},
          {"name": "totalSeats", "type": "int"}
        ]
      }
    }
  ]
}
yaml

Example Referencing an Avro Fragment from an Async API

asyncapi: 2.6.0
info:
  title: Example AsyncAPI Spec (Inline Avro)
  version: '1.0.0'
channels:
  myChannel:
    publish:
      message:
        schemaFormat: application/vnd.apache.avro;version=1.9.0
        payload:
          $ref: AmericanFlightDataType.avsc
yaml
For AVRO schema documents, .avsc is the default extension, but .json files are also supported.

Example AsyncAPI 2.0 Specification

This example is a typical event-driven process that is documented for easy reuse. It has a service with two channels, one that books the trade and another that gets the result of the booking asynchronously.

Sections in the example specification are:

  • AsyncAPI

    Identifies the API model as AsyncAPI and specifies the title and version of the API spec.

  • Channels

    • The book_trade channel enables you to specify the buy/sell order, symbol, and number of shares you would like to purchase.

    • The trade_result channel returns the result of the transaction.

To try the example, create a new AsyncAPI specification in Design Center and copy the following code directly into API Designer:

For documentation on using API Designer to work with your specification, see API Designer.

See Also