Import and Implement an API Specification from Exchange

Import an AsyncAPI, OAS, or RAML API spec into a new or existing Mule project.

If you’re using Mule runtime engine (Mule) 4.1.3 and earlier, or if you prefer to import an API specification that isn’t available in Exchange, you can import an API spec from a local file or from MuleSoft VCS.

If you can’t access Exchange from your work environment, you can import an API specification from your local Maven installation.

Import and Implement an API Specification from Exchange Into a New Project

In the taskbar, select File > New > Mule Project.
Type a name for your project.
In the Runtime section, select the Mule runtime version appropriate for your project:
1. Select a Mule runtime engine version 4.1.4 or later for an OAS or RAML API spec.
2. select a Mule runtime engine version 4.5.0 or later for an AsyncAPI spec.
In the API Specification section, select the From Exchange or Maven tab.
Click the Add icon (), and select From Exchange.
Select your Anypoint Platform username.

If you’re not logged in, click Add Account to add your Anypoint Platform account.
From the list of available APIs, select one or more and click Add.

To list all available APIs, type a * character in the search bar and press Enter.
To select the version of the API to import, use the Selected Modules table.
Click Finish.

By default, Studio scaffolds your API spec. To prevent Studio from creating flows out of your API spec, unselect Scaffold Flows From These API Specifications.

Manage the API specifications linked to Exchange in your project from the API specification project management view by clicking the Manage Mule Project APIs icon () in the taskbar.

Import and Implement an API Specification from Exchange Into an Existing Project

Right-click on your project in the Package Explorer, select Mule, and then select Manage APIs.
Click the Add icon (), and select From Exchange.
Select your Anypoint Platform username.

If you’re not logged in, click Add Account to add your Anypoint Platform account.
Select the API from the list of available APIs and click Add.

You can choose more than one API to import.

To list all available APIs, type a * character in the search bar and press Enter.

You can select the version of the API to import in the Selected Modules table.
Click Finish.

By default, Studio scaffolds your API spec. To prevent Studio from creating flows out of your API spec, unselect Scaffold Flows From These API Specifications.

Manage the API specifications linked to Exchange in your project from the API specification project management view by clicking the Manage Mule Project APIs icon () in the taskbar.

If you want Studio to list your API when searching in Exchange, you must mark your API specification published as an asset as stable.

Rescaffold an API Specification in a Mule Project

After changing your API spec, such as adding a new endpoint, rescaffold the spec to update your Mule project.

Right-click on the XML file of your Mule project.
Select API Specs, the name of your Mule project, and Generate Flows.

If the rescaffolding process of your project is successful, your implementation XML file includes a new flow.

Implement AsyncAPI Specifications

Studio supports the implementation of AsyncAPI 2.6 specs. When creating an implementation project, Studio imports and scaffolds an AsyncAPI spec 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.

You must have access to a supported AsyncAPI specification hosted on Anypoint Exchange. If your AsyncAPI specification isn’t published to Exchange, see Publishing API Specifications. To create an AsyncAPI specification before publishing to Exchange, see AsyncAPI Specifications.

Scaffolding Fundamentals for AsyncAPI Implementations

When scaffolding an AsyncAPI specification into a Mule project, Studio:

Introspects the AsyncAPI specification
Considers one spec at a time
Treats the imported spec as a modification of an existing spec and evaluates it for rescaffolding
Creates a new Mule project with a separate flow for each publish operation in the specification
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
Makes the APIkit for AsyncAPI module available for use in the project

The module provides the following operations:
- Publish (<apikit-asyncapi:publish/>): AsyncAPI subscribe operations in the specification are available for configuration as AsyncAPI Publish operations.
- Message Listener (<apikit-asyncapi:message-listener/>): AsyncAPI publish operations in the specification are configurable Message Listener (not Publish) operations.
  
  The scaffolder transforms each publish operation into a Message Listener operation.
  
  If a Message Listener receives an invalid message, it’s sent to the dead-letter queue (you must set up one dead-letter queue).
Generates a global-configs.xml file with connection configurations for Message Listener and Publish operations in the AsyncAPI module and for any connectors the module depends on.

Errors can occur during the scaffolding process:

If no channels are defined in the specification
If unsupported message broker protocols are used

For supported protocols, see Supported Message Brokers in APIkit for AsyncAPI Module Reference. For supported bindings and channels, see Supported Bindings and Parametrized Channels.

Studio doesn’t support the scaffolding of AsyncAPI, Avro, OAS, or JSON schema fragment files that are referenced from API specs. The scaffolder doesn’t add these fragments as project dependencies when you import the specification from Exchange. However, you can scaffold and reference fragments that are specified inline, within the spec. RAML fragments imported from Exchange aren’t affected by this limitation.

Considerations About Importing and Scaffolding AsyncAPI Specs and Fragments

You can’t create AsyncAPI specs or fragments in Studio.
AsyncAPI APIs use message brokers for communication.

For supported protocols, see Supported Message Brokers in APIkit for AsyncAPI Module Reference.
If the imported Async API has an Avro fragment, see Implementing and Validating Avro Schemas in APIkit for AsyncAPI Module.

Example AsyncAPI 2.6 Specification

Following is an example that you can replicate 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.

asyncapi: '2.6.0'
info:
  title: Orders AsyncAPI
  version: '1.0.0'
  description: Orders API
  license:
    name: Anypoint MQ
    url: https://license.com
  contact:
    name: Max Muley
    email: max@salesforce.com
    url: http://salesforce.com
defaultContentType: application/json
tags:
  - name: Orders API
    description: API for orders
servers:
  AMQ-prod:
    url: https:://your_MQ_server_URL_here
    protocol: anypointmq
    protocolVersion: v1
    description: Anypoint MQ broker
  kafka-prod:
    url: your_kafka_URL_here
    protocol: kafka
    description: kafka broker
  sfpubsub-prod:
      protocol: salesforcepubsub
      protocolVersion: v1
      url: api.pubsub.salesforce.com
      description: Salesforce pub sub for Platform events production
  solace-server:
    protocol: solace
    variables:
      port:
        enum:
        - '1000'
    bindings:
      solace:
        msgVpn: your_solace_vpn_here
        bindingVersion: 0.4.0
    protocolVersion: 1.0.0
    url: mySolaceURL
channels:
  order-placed:
    description: new orders channel
    servers:
      - AMQ-prod
    publish:
      operationId: listen-order-placed
      description: listen for new order events
      summary: Order Placed Event
      message:
        $ref: '#/components/messages/OrderPlaced'
    subscribe:
      operationId: publish-order-placed
      description: publish new order events
      summary: Order Placed Event
      message:
        $ref: '#/components/messages/OrderPlaced'
  order-updated:
    description: updated orders channel
    servers:
      - solace-server
    publish:
      operationId: listen-order-updated
      description: listen for updated order events
      summary: Order updated Event
      bindings:
        solace:
          bindingVersion: 0.3.0
          destinations:
          - destinationType: queue
            queue:
              name: listen-order-updated
              topicSubscriptions:
              - acmeretail/onlineservices/order/updated/v1/*/*
              - acmeretail/onlineservices/order/updated/v2/*/*
      message:
        $ref: '#/components/messages/OrderUpdated'
    subscribe:
      operationId: publish-order-updated
      description: publish updated order events
      summary: Order updated Event
      bindings:
        solace:
          bindingVersion: 0.3.0
          destinations:
          - destinationType: queue
            queue:
              name: C360.CUSTOMERS
              topicSubscriptions:
              - acmeretail/onlineservices/order/updated/v1/*/*
              - acmeretail/onlineservices/order/updated/v2/*/*
      message:
        $ref: '#/components/messages/OrderUpdated'
  order-cancelled:
    description: orders cancelled channel
    servers:
      - AMQ-prod
    publish:
      operationId: listen-order-cancellations
      description: listen for order cancellation events
      summary: Order Cancelled Event
      message:
        $ref: '#/components/messages/OrderCancelled'
    subscribe:
      operationId: publish-order-cancellations
      description: publish order cancellation events
      summary: Order Cancelled Event
      message:
        $ref: '#/components/messages/OrderCancelled'
  order-confirmed:
    description: orders confirmed channel
    servers:
      - sfpubsub-prod
    publish:
      operationId: listen-order-confirmations
      description: listen for order confirmation events
      summary: Order Confirmed Event
      message:
        $ref: '#/components/messages/OrderConfirmedSub'
    subscribe:
      operationId: publish-order-confirmations
      description: publish order confirmation events
      summary: Order Confirmed Event
      message:
        $ref: '#/components/messages/OrderConfirmedPub'
  order-backordered:
    servers:
      - kafka-prod
    description: orders backordered channel
    publish:
      operationId: listen-order-backordered
      description: listen for backorder events
      summary: Backorder Event
      message:
        $ref: '#/components/messages/BackOrder'
    subscribe:
      operationId: publish-order-backordered
      description: publish backorder events
      summary: Backorder Event
      message:
        $ref: '#/components/messages/BackOrder'
components:
  messages:
    OrderPlaced:
      payload:
        type: object
        properties:
          orderId:
            type: string
          customerName:
            type: string
          email:
            type: string
          items:
            type: array
            items:
              type: object
              properties:
                productId:
                  type: string
                productName:
                  type: string
                quantity:
                  type: integer
                price:
                  type: number
              required: [productId, productName, quantity, price]
              additionalProperties: false
        required: [orderId, customerName, email, items]
        additionalProperties: false
    OrderConfirmedPub:
      summary: order message pub
      contentType: application/json
      payload:
        type: array
        orderconfirmation:
          type: object
          properties:
            orderId__c:
              type: string
            email__c:
              type: string
            required: [orderId, email]
            additionalProperties: false
    OrderConfirmedSub:
      summary: order message sub
      contentType: application/json
      payload:
        type: object
        properties:
          event:
            type: object
            properties:
              orderId__c:
                type: string
              email__c:
                type: string
        required: [orderId, email]
        additionalProperties: false
    OrderCancelled:
      payload:
        type: object
        properties:
          orderId:
            type: string
          email:
            type: string
          reason:
            type: string
        required: [orderId, email, reason]
        additionalProperties: false
    BackOrder:
      payload:
        type: object
        properties:
          orderId:
            type: string
          email:
            type: string
        required: [orderId, email]
        additionalProperties: false
    OrderUpdated:
      contentType: application/json
      description: Shows changes to customer information including name, address and
        loyalty status
      payload:
        "$ref": "#/components/schemas/Order_JSON"
      schemaFormat: application/vnd.aai.asyncapi+json;version=2.0.0
      x-ep-application-domain-id: p4oo2ehrcpf
      x-ep-application-domain-name: OnlineServices
      x-ep-custom-attr-confidential: 'true'
      x-ep-event-id: 66gdcid5pht
      x-ep-event-name: Customer Created
      x-ep-event-state-id: '2'
      x-ep-event-state-name: RELEASED
      x-ep-event-version: 2.0.2
      x-ep-event-version-displayname: ''
      x-ep-event-version-id: 29btjydowi0
      x-ep-shared: 'true'
  schemas:
    Order_JSON:
      "$schema": http://json-schema.org/draft-07/schema#
      properties:
        customer_id:
          description: The unique identifier of the customer
          type: string
        insight_description:
          description: A brief description of the insight
          type: string
        insight_type:
          description: The type of insight (e.g., demographic, behavioral, transactional)
          type: string
        insight_value:
          description: The value or result of the insight
          type: string
        timestamp:
          description: The timestamp when the insight was generated
          format: date-time
          type: string
      required:
      - customer_id
      - insight_type
      - insight_description
      - insight_value
      - timestamp
      title: CustomerInsight
      type: object
      x-ep-application-domain-id: a3hbbd7unz2
      x-ep-application-domain-name: Customer360
      x-ep-schema-id: 6dqkacw0k70
      x-ep-schema-name: Customer Insight
      x-ep-schema-state-id: '1'
      x-ep-schema-state-name: DRAFT
      x-ep-schema-version: 0.1.0
      x-ep-schema-version-displayname: ''
      x-ep-schema-version-id: u15ylfss2qx
      x-ep-shared: 'false'