Hear from Salesforce leaders on how to create and deploy Agentforce agents.
Register now
Contact Us 1-800-596-4880
  1. Homepage
  2. Studio
  3. Importing API Specifications

  4. From Exchange

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

  1. In the taskbar, select File > New > Mule Project.

  2. Type a name for your project.

  3. 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.

  4. In the API Specification section, select the From Exchange or Maven tab.

  5. Click the Add icon (A plus sign icon), and select From Exchange.

  6. Select your Anypoint Platform username.

    If you’re not logged in, click Add Account to add your Anypoint Platform account.

  7. 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.

  8. To select the version of the API to import, use the Selected Modules table.

  9. 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 (A stylized letter i with a curved roof over it) in the taskbar.

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

  1. Right-click on your project in the Package Explorer, select Manage Dependencies, and then select Manage APIs.

  2. Click the Add icon (A plus sign icon), and select From Exchange.

  3. Select your Anypoint Platform username.

    If you’re not logged in, click Add Account to add your Anypoint Platform account.

  4. 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.

  5. 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 (A stylized letter i with a curved roof over it) 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.

  1. Right-click on the XML file of your Mule project.

  2. 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:

    • Subscribe (<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 operations. The system publishes messages to a channel, and the Mule application listens for these messages.

      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.

      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:

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

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.

See Also