Hear from Salesforce leaders on how to create and deploy Agentforce agents.
Register now
Contact Us 1-800-596-4880
  1. Homepage
  2. Anypoint Code Builder
  3. Implementing APIs

  4. Implementing AsyncAPI Specifications

Open Beta Release: The cloud IDE is in open beta. Any use of Anypoint Code Builder in its beta state is subject to the applicable beta services terms and conditions, available from the IDE.

Implementing AsyncAPI Specifications

logo cloud IDE Cloud IDE

logo desktop IDE Desktop IDE

Anypoint Code Builder supports the implementation of AsyncAPI 2.6 and 2.0 specifications in projects running on Mule runtime version 4.6 or later. When creating an implementation project, Anypoint Code Builder imports and scaffolds an AsyncAPI specification hosted on Anypoint Exchange into an implementation project that you can develop further according to your business needs.

Async APIs rely on message brokers to send and receive messages between different services or components in a decoupled manner. The services can send and receive messages without knowing the specific details of the recipient or sender, thus enabling asynchronous communication. For communicating with the recipient and sender, the message brokers use specific protocols. See Supported Message Brokers in APIkit for AsyncAPI Module Reference.

Before You Begin

Scaffolding Fundamentals

Before you implement an AsyncAPI specification with Anypoint Code Builder, it’s important to understand the scaffolding process at a high level.

When scaffolding an AsyncAPI specification into a Mule project (implementation or integration), Anypoint Code Builder:

  • Introspects the AsyncAPI specification

  • Considers one specification at a time

  • Treats the imported specification as a modification of an existing specification and evaluates it for rescaffolding

  • Creates a new Mule project with a separate flow for each publish operation in the specification

    See Example: Scaffolded Flows.

  • Generates an empty XML file with the name of your Mule project if the AsyncAPI spec doesn’t include a publish operation

  • Produces the configuration properties file dev-properties.properties file in the src/main/resources directory of your Mule project

    See Example: Configuration Properties File.

  • Makes the APIkit for AsyncAPI Module (AsyncAPI Module) available for use in the project

    The module provides the following operations:

    • Subscribe (<apikit-asyncapi:publish/>): AsyncAPI subscribe operations in the specification are available for configuration as AsyncAPI Publish operations. See the implemented example in Example: Scaffolded Flows.

    • Message Listener (<apikit-asyncapi:message-listener/>): AsyncAPI publish operations in the specification are configurable as Message Listener operations. The system publishes messages to a channel, and the Mule application listens for these messages. See examples in Example: Scaffolded Flows.

      The scaffolder transforms each publish operation into a Message Listener operation allowing the Mule application to read from the specified channel and process the published messages.

  • Generates a global-configs.xml file with connection configurations for Message Listener and Publish operations in the AsyncAPI Module and for any connectors that module depends on

    See Example: Connection Configurations.

Errors can occur during the scaffolding process:

  • If no channels are defined in the specification

  • For unsupported message broker protocols

    For supported protocols, see Supported Message Brokers in APIkit for AsyncAPI Module Reference.

Anypoint Code Builder supports scaffolding these schema fragment files if they’re referenced from API specs:

Avro JSON RAML

AsyncAPI

Yes

Yes

No

GraphQL

No

No

Yes

OData

No

No

Yes

REST

No

No

Yes

SOAP

No

No

Yes

If you add a fragment that isn’t supported, the scaffolder doesn’t add these fragments as project dependencies when you import the spec from Exchange. However, you can scaffold schemas that are specified inline within the spec.

Scaffold an AsyncAPI Specification into a Mule Project

You can scaffold an AsyncAPI specification into a new or existing Mule project:

  • To scaffold an AsyncAPI specification into a new implementation project, follow the procedure in Scaffold an AsyncAPI Specification into a New Project.

  • To scaffold or re-scaffold an AsyncAPI specification into an existing Mule project (implementation or integration), see Scaffold or Re-Scaffold an AsyncAPI Specification into an Existing Project. Re-scaffolding can be useful when the specification version is updated to introduce a new operation or server. If the specification contains a new server, the scaffolder adds a new configuration for it to the Mule project.

    When re-scaffolding, the scaffolder acts on new combinations of channel, server, and publish and subscribe operations groupings in the specification and doesn’t re-scaffold combinations that aren’t new.

Scaffold an AsyncAPI Specification into a New Project

Create an implementation project from an AsyncAPI specification that is hosted on Anypoint Exchange. When creating the project, Anypoint Code Builder scaffolds the specification into an interface that you can implement as a Mule app.

  1. Meet the prerequisites in Before You Begin.

  2. In the activity bar of the IDE, click the (Anypoint Code Builder) icon.

    Anypoint Code Builder icon highlighted in the activity bar

  3. From Quick Actions, click Implement an API:

    *Implement an API* link highlighted in the *Getting Started* section

  4. Complete the Implement an API Specification form:

    Form for starting an implementation project
    Field Name Field Value

    Project Name

    Unique name for your project.

    This name is used as the title and name of the project file. For example, if the project name is My Project, the project file name is my-project.

    Project Location

    Your home directory or another directory you create.

    See Adding Folders to Your Home Directory.

    Don’t create the project within another project directory.

    Search an API Specification from Exchange

    Name of the specification in Exchange. Activate Show filters to narrow your search results. See Filtering Search Results for more information.

    Mule runtime

    Mule runtime version to use for your project.

    Java Version

    Java version to use for Mule.

    You can select any of the supported Mule runtime and Java versions. The IDE saves your version settings to the project’s mule-artifact.json file.

  5. Search for an API spec on Exchange:

    1. Start typing the name of an API spec.

    2. Press Enter to display a list of search results.

    3. Click Add Asset to add the selected API spec:

      Only supported versions of the AsyncAPI specifications in Exchange are available for scaffolding. Unsupported versions don’t appear in the search results.

      List of AsyncAPI specification assets found in Exchange

  6. Click Create Project.

    When you create the project, Anypoint Code Builder:

    • Scaffolds your API specification into the new Mule project that opens to a configuration XML file with scaffolded flows (flows.xml), for example:

      AsyncAPI implementation project in the IDE

      The configuration XML file includes the interface for your implementation project, with flows that contain Message Listener (<apikit-asyncapi:message-listener/>) configurations for each publish operation in the specification.

    • Adds the API specification as a dependency in your project’s pom.xml file, for example:

      <dependency>
    <groupId>e21dd38b-8231-45bf-aaa7-abde2072d538</groupId>
    <artifactId>my-asyncapi-example</artifactId>
    <version>1.0.0</version>
    <classifier>evented-api</classifier>
    <type>zip</type>
</dependency>
      xml

    • Adds the Mule and Java versions to the project’s mule-artifact.json file, for example:

      {
    "minMuleVersion": "4.7.0",
    "javaSpecificationVersions": [
      "17"
    ]
}
      json

  7. Provide business logic to implement this interface within the Mule app:

    Define your business logic by configuring connector operations and processing components, as needed for your use cases. Provide configuration property values to the dev-properties.properties file. Optionally, create and configure additional flows or subflows for your processing requirements.

    To find guidance on configuring components, debugging, performing unit testing on your application, and other tasks, see Developing Integrations. For information about connectors and processors for configuring your business logic, see Reference.

    For an example of an AsyncAPI specification, the scaffolded interface, and business logic for processing some orders within a Mule application, see Examples.

Scaffold or Re-Scaffold an AsyncAPI Specification into an Existing Project

Scaffold or re-scaffold an AsyncAPI specification from Exchange into an existing project in Anypoint Code Builder. Before re-scaffolding, review the important note about which new configurations are scaffolded into your project.

  1. Meet the prerequisites in Before You Begin.

    Use of AsyncAPI features in the IDE requires enablement by an Anypoint Platform organization administrator.

  2. In Anypoint Code Builder, open your project.

  3. Open the Command Palette.

  4. Provide this command:

    MuleSoft: Import Asset from Exchange
    command

  5. Select AsyncAPI from the list of assets.

  6. If prompted, log in to Anypoint Platform, allowing the extension to sign in and open an external web site and to open Visual Studio Code.

  7. Type the full name or partially matching name of your specification, for example:

    My AsyncAPI Spec

  8. Wait for the IDE to load a list of matches to the name, and then select your AsyncAPI specification.

    Only supported versions of the AsyncAPI specifications in Exchange are available for scaffolding. Unsupported versions don’t appear in the search results.

  9. When prompted for a version, select the version of the API to import, such as 1.0.0 or 2.0.0.

  10. Select Yes when prompted to scaffold the API dependency.

    When the scaffolding process is complete, the IDE opens to a configuration XML file that contains the scaffolded flows (flows.xml). If you re-scaffolded the specification, see the important note about which new configurations are scaffolded into your project.

  11. Provide business logic to implement this interface within the Mule app:

    Define your business logic by configuring connector operations and processing components, as needed for your use cases. Provide configuration property values to the dev-properties.properties file. Optionally, create and configure additional flows or subflows for your processing requirements.

    To find guidance on configuring components, debugging, performing unit testing on your application, and other tasks, see Developing Integrations. For information about connectors and processors for configuring your business logic, see Reference.

    For an example of an AsyncAPI specification, the scaffolded interface, and business logic for processing some orders within a Mule application, see Examples.

Deploy an Implementation

Deploy the implementation to CloudHub and CloudHub 2.0 or to another host. You can deploy to CloudHub or CloudHub 2.0 from Anypoint Code Builder. For other deployment options, see Deployment Options.

Examples

The examples describe an API specification and implementation for processing orders and sending order status notifications by email and Slack.

Example: AsyncAPI 2.6 Specification

The following example defines an API specification that uses Anypoint MQ and Kafka protocols. The specification defines channelsLeaving the Site for orders (new, confirmed, and cancelled orders) that use Anypoint MQ, and it defines a channel that uses Kafka for backorders (items that aren’t in stock). Each channel includes a publish and subscribe operation. The serverLeaving the Site settings in the specification define message brokers that determine the connectors to use (indirectly) when publishing events or subscribing to events through operations in the AsyncAPI module.

1 AMQ-prod configures an Anypoint MQ broker.

You can discover the URL for an MQ broker from the region that you select when creating the queue. See the copy button in Create a Queue, and see Configuring Client Apps.
2 Kafka-prod configures a locally hosted Kafka broker.
3 order-placed configures an Anypoint MQ channel for publishing (listening for) and subscribing to (publishing) orders. Similarly configured channels are order-cancelled and order-confirmed.
4 order-backordered configures a Kafka channel for publishing (listening for) and subscribing to (publishing) backorders.
5 components defines the structure of messages for the different types of orders, which include OrderPlaced, OrderCancelled, OrderConfirmed, and BackOrder.

Example: Scaffolded Flows

When scaffolding the specification into an implementation project, Anypoint Code Builder creates a flow (<flow/>) for each publish operation and transforms the publish operation into a Message Listener source from the AsyncAPI module for APIkit (<apikit-asyncapi:message-listener/>). Each flow also includes a Logger component. For more information about the module, see APIkit for AsyncAPI Module Reference.

The scaffolder generates a flow.xml file from the specification. The scaffolder generates the following XML from the AsyncAPI specification example:

1 AMQ-prod in <apikit-asyncapi:server value="AMQ-prod" /> identifies an Anypoint MQ server connection. For more information, see Example: Connection Configurations.
2 Kafka-prod in <apikit-asyncapi:server value="Kafka-prod" /> identifies a Kafka server connection. For more information, see Example: Connection Configurations.

The following example adds business logic to the scaffolded flows:

  • LISTEN:listen-order-placed listens for orders and, when triggered, uses a DataWeave expression to check for sufficient inventory. If enough items exist in the inventory, the flow configures a Publish operation to publish order data to the order-confirmed channel, which triggers the LISTEN:listen-order-confirmations flow. If not, the flow adds a Publish operation to publish order data to a order-backordered channel, which triggers the LISTEN:listen-order-backordered flow.

  • LISTEN:listen-order-confirmations listens for order confirmations and, when triggered, sends order information to the notification-flow subflow, which sends confirmation notices through Slack and email (see Example: Notification Subflow).

1 After the Message Listener in flow LISTEN:listen-order-placed is triggered by an order, an HTTP request operation (<http:request/>) requests and stores inventory data in the target variable inventory.
2 The Choice component (<choice/>) checks the availableStock value in the target variable (vars.inventory.stockDetails.availableStock) against a quantity value from the order payload (payload.items.quantity[0]). The quantity value comes from an OrderPlaced message that triggers the flow.

If sufficient stock is available, a Set Payload component (<set-payload/>) configures a confirmation message that the Publish operation (<apikit-asyncapi:publish/>) submits to the order-confirmed channel, which triggers the LISTEN:listen-order-confirmations flow. If not, the flow publishes a message to the order-backordered channel, which triggers the flow LISTEN:listen-order-backordered.
3 The Message Listener in flow LISTEN:listen-order-confirmations listens for activity on the Anypoint MQ channel order-confirmed. When triggered, the flow configures its <set-payload/> component to create an order confirmation message. The Flow Reference (<flow-ref/>) sends this message for processing within the notification-flow subflow.
4 The flow LISTEN:listen-order-backordered is triggered by LISTEN:listen-order-placed when inventory is insufficient.

Example: Connection Configurations

The scaffolding process generates global-configs.xml for server connection configurations defined in the specification.

The connection configuration for the AsyncAPI module within <apikit-asyncapi:config/> references the connection configurations for Kafka and Anypoint MQ connectors. The scaffolding process adds the connectors to the project based on the serverLeaving the Site and channelLeaving the Site configurations in the AsyncAPI specification.

  • In flows, Publish operations (<apikit-asyncapi:publish/>) use the connection configurations when publishing to specified channel and server combinations. The flows publish to Kafka and Anypoint MQ channels on Kafka-prod or AMQ-prod servers.

  • In flows, Message Listener operations (<apikit-asyncapi:message-listener/>) are automatically configured to listen on a specific channel based on a server value setting (Kafka-prod or AMQ-prod). This value matches one of the serverKey settings in the AsyncAPI connection configuration (<apikit-asyncapi:config/>).

When adding business logic to your scaffolded project, you can add other connection configurations to global-configs.xml, including any connector operations you add to your flows or subflows in the application. The following example adds connection configurations for HTTP, Email, and Slack connector operations. You can define configuration properties for these, such as ${email.password} in a properties file.

<!-- additional connection configuration examples -->
  <http:request-config name="HTTP_Request_config" basePath="path" > (1)
    <http:request-connection protocol="HTTP" host="example.com" />
  </http:request-config>

  <http:listener-config name="HTTP_Listener_config" > (2)
    <http:listener-connection host="0.0.0.0" port="8081" />
  </http:listener-config>

  <email:smtp-config name="Email_SMTP"> (3)
    <email:smtps-connection host="smtp.gmail.com" password="${email.password}" user="${email.username}">
      <tls:context>
        <tls:trust-store insecure="true"></tls:trust-store>
      </tls:context>
    </email:smtps-connection>
  </email:smtp-config>

  <slack:config name="Slack_Config"> (4)
    <slack:token-connection token="${slack.token}" />
  </slack:config>
xml
1 HTTP Request connection configuration example
2 HTTP Listener connection configuration example
3 Email SMTP connection configuration example
4 Slack connection configuration example

Example: Configuration Properties File

Anypoint Code Builder generates a dev-properties.properties file in the src/main/resources directory of your implementation project.

The specification example defines server settings for an Anypoint MQ broker. To listen for and publish messages to an Anypoint MQ queue, you must supply a clientAppId and clientSecret for an MQ client app. The associated api-path setting is generated automatically during the scaffolding process.

#Fri Jun 07 09:32:50 PDT 2024
anypointmq.server.AMQ-prod.clientAppId=
anypointmq.server.AMQ-prod.clientSecret=
api.path=resource\:\:e21dd38b-8231-45bf-aaa7-abde2072d538\:my-asyncapi-example\:1.0.0\:evented-api\:zip\:anypointmq-kafka-orders-demo-final.yaml
properties

You can add additional properties to this file. The email and slack examples are for Email and Slack connector operations in the notifications subflow.

#Fri Jun 07 17:05:33 PDT 2024
anypointmq.server.AMQ-prod.clientAppId=my_client_app_id_here
anypointmq.server.AMQ-prod.clientSecret=my_client_app_secret_here
slack.token=my_slack_token_here
email.host=smtp.gmail.com
email.username=me@gmail.com
email.password=my_gmail_password_here
api.path=resource\:\:8dbc2756-83d6-4a1c-91c4-6eafbe7d7ae0\:async-amq-kafka-orders\:1.0.2\:evented-api\:zip\:anypointmq-kafka-orders-demo-compliant.yaml
properties

For help with configuration properties, including secure properties for passwords and other sensitive data, see Defining and Securing Properties for a Mule Application.

Example: Notification Subflow

The subflow (<sub-flow/>) in notifications.xml implements the business logic for sending order confirmation messages by email and Slack. This file isn’t generated by the scaffolder.

When triggered by the Flow Reference component (<flow-ref/>) in the LISTEN:listen-order-confirmations flow, the notifications subflow sends order confirmation messages.

1 Transforms payload output from the LISTEN:listen-order-confirmations flow into Mule variables that capture confirmation message data
2 Posts the Slack confirmation message by using the <slack:post-message/>`* operation from Slack Connector
3 Emails the confirmation message by using the <email:send/> operation from Email Connector

See Also