---
schema_version: "1"
id: 6c24f630658c27176624bb615344b37ddef133ffdccea9d96fa259b20cdbd219
title: Import and Implement an API Specification from Exchange
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/studio/import-api-specification-exchange.md
canonical_url: https://docs.mulesoft.com/studio/import-api-specification-exchange
source_site: docs.mulesoft.com
content_type: documentation
content_hash: cdd7fdf56dd01888ce0c49b2124876f41335702ac90568c6479ac7ae1cee17ae
description: MuleSoft Documentation Site
latest: true
---
---
product: Studio
---
# Import and Implement an API Specification from Exchange
> For the full documentation index, see: https://docs.mulesoft.com/llms.txt
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](https://docs.mulesoft.com/studio/import-api-specification-local-file) or
[from MuleSoft VCS](https://docs.mulesoft.com/studio/import-api-specification-design-center).
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 (), 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
() 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 (), 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
() in the
taskbar.
> [!NOTE] 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](https://docs.mulesoft.com/apikit/latest/apikit-asyncapi-module-reference#supported-message-brokers)
in APIkit for AsyncAPI Module Reference.
> [!NOTE] 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](https://docs.mulesoft.com/design-center/design-publish). To create an AsyncAPI
> specification before publishing to Exchange, see
> [AsyncAPI Specifications](https://docs.mulesoft.com/design-center/design-async-api).
### 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** (``): AsyncAPI **subscribe** operations in the
specification are available for configuration as AsyncAPI **publish** operations.
- **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:
- If no channels are defined in the specification
- If unsupported message broker protocols are used
For supported protocols, see
[Supported Message Brokers](https://docs.mulesoft.com/apikit/latest/apikit-asyncapi-module-reference#supported-message-brokers)
in APIkit for AsyncAPI Module Reference. For supported bindings and channels, see
[Supported Bindings and Parametrized Channels](https://docs.mulesoft.com/apikit/latest/apikit-for-asyncapi-supported-bindings).
Studio supports scaffolding these schema fragment files if they’re referenced from API specs:
| API Type | Avro | JSON | RAML | WSDL |
|---|
AsyncAPI | Yes | Yes | No | No |
OData v2 | No | No | Yes | No |
REST | No | No | Yes | No |
SOAP | No | 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.
### 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](https://docs.mulesoft.com/apikit/latest/apikit-asyncapi-module-reference#supported-message-brokers)
in APIkit for AsyncAPI Module Reference.
- If the imported Async API has an Avro fragment, see
[Using Avro Schemas with APIkit for AsyncAPI](https://docs.mulesoft.com/apikit/latest/apikit-asyncapi-avro-support).
## 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.
```yaml
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"
```
## See Also
- [Design, Publish, and Implement API Specifications in Anypoint Studio](https://docs.mulesoft.com/studio/api-development-studio)
- [Sync Your API Projects with MuleSoft VCS Using API Sync](https://docs.mulesoft.com/studio/api-sync)
- [Add Your Anypoint Platform Account to Access Organization Resources](https://docs.mulesoft.com/studio/set-credentials-in-studio-to)