Exchange API
Asset Creation
Exchange API v2 provides a new interface to create assets.
You can continue using the API provided by v1. The only change to use it is replacing v2
with v1
in the URL.
Exchange API version 2 can upload all supported asset types, including connectors, examples, templates, mule applications, and policies. These asset types are supported:
REST APIs
- An API specification that can be represented in RAML format or OAS (Swagger) format.SOAP APIs
- An API specification in WSDL format.HTTP APIs
- A placeholder for an endpoint for use by private Exchange users who want to manage the endpoint with API Manager.API Groups
- A set of APIs bundled into a single asset.Instead of requesting access to multiple APIs to satisfy a use case, a developer can access the group in one step.API Spec Fragments
- A RAML document that has a version and an identifier, but is not a complete RAML specification.API spec fragments are also known as RAML fragments.Custom
- A description and an optional file to explain aspects of your system, to provide instructional videos, or to describe a product or organizational documentation.Connectors
- Packaged connectivity to an endpoint developed and deployed on Anypoint Platform with third-party APIs and standard integration protocols. Use connectors within your application’s flows to send and receive data using a protocol or specific API. Anypoint Studio comes with many bundled connectors, and Exchange has many more.Templates
- Packaged integration patterns built on best practices to address common use cases. You can add your information such as user credentials to complete the template’s use case or solution, and you can customize or extend templates as needed.Examples
- Applications that are ready to run in Anypoint Studio and demonstrate a use case or solution.Policies
- Configuration modules to extend the functionality of an API and enforce capabilities such as security.Mule Application
- An application used to perform system integration.
Create an Asset
There are two ways to upload an asset using this API.
The first way is to specify the properties in the multipart form data. This is similar to uploading an asset with the Exchange API version 1. A POM file is automatically created for the uploaded asset.
The second way is to upload the asset properties in a pom.xml
file. If you do this, then two files are uploaded to create the asset.
Attempting to create an asset with defined asset properties in both multipart form data and a POM file causes an error.
Exchange API version 2 allows users to upload an asset in a synchronous or asynchronous way. We recommend the synchronous method for manual publication, and the asynchronous method for automated publication or to know the status of the publication process.
To use the synchronous method, add the header x-sync-publication:true
. To use the asynchronous method, add the header x-sync-publication:false
or send a request without the x-sync-publication
header.
If the asset is published asynchronously, then a response like this is returned:
{
"publicationStatusLink":"https://anypoint.mulesoft.com/exchange/api/v2/organizations/67ac7cde-c02c-457f-b826-da2474e63d5a/assets/67ac7cde-c02c-457f-b826-da2474e63d5a/wsdl-asset/1.0.0/publication/status/d47a22a5-90f6-49eb-bfd0-d9fff575e022"
}
The endpoint publicationStatusLink
provides the asset publication status.
Before executing the examples, obtain a token with the instructions in the Anypoint Platform Token
section. In each example, replace ANYPOINT_TOKEN
with your token.
You can send HTTP commands with cURL, Postman, or another application. These examples use cURL.
In all examples:
- Replace
:organizationId
with the organization ID of the organization where the asset will be published. - Replace
:groupId
with the group ID of the asset to publish. - Replace
:assetId
with the asset ID of the asset to publish. - Replace
:version
with the version of the asset to publish.
Upload an Asset with Properties in Multipart Form Data
Before trying any of these examples, understand all multipart fields in the request.
Asset Properties
All assets have these multipart field properties:
name
description
type
dependencies
keywords
files
Assets of some types have additional properties defined with the properties
prefix.
For example, to define an asset’s apiVersion
: properties.apiVersion = v1
Common asset properties include:
mainFile
: The name of the main file inside the zip archive. The main file must be in the root folder of the zip archive.apiVersion
: Identifies the API version of the asset.apiVersion
is used only for API asset types. Each major version of the asset must have a differentapiVersion
.assetLink
: The URL of an external API.
Files
Specify each uploaded file by specifying its packaging
and classifier
after the prefix files
.
For example, to upload a RAML file in a zip archive, use files.raml.zip=@/...
, where raml
is the classifier and zip
is the packaging of the file.
It is not necessary that each file has a special name to be uploaded, as long as the classifier and packaging are well defined.
Main properties
These are the main properties of the asset. The name
is required. If no file is uploaded from which the type can be inferred, then the type
is required.
name
: The visible name of the asset.description
: The description of the asset being created.type
: The type of the asset to be created.If notype
is specified, thentype
is inferred based on the file's classifier.dependencies
: A string of comma-separated dependencies, defined asdependencies=GROUP_ID:ASSET_ID:VERSION,GROUP_ID:ASSET_ID:VERSION
.keywords
: A string of comma-separated values that represents the values to be saved as an asset's attributes.You can find assets by usingkeywords
in the search. For example,keywords
could be defined as:keywords=api,raml,auth,jwt,token
Fat Package Generation
When an API specification asset is published, including RAML REST APIs, OAS REST APIs, and RAML fragments, the original zip file is modified and a new zip file is created.
After the asset is created, a file named exchange.json is added inside the original zip file with all the metadata information relevant to that API specification. The file is created with the information submitted in the publication form. If the file is already in the zip file, it is overwritten. If dependencies are declared in the publication form, and the original zip contains a directory with the name exchange_modules, then this directory is deleted.
In addition, a version of the same zip file called a fat package is created as part of the asset files. Its classifier has the prefix fat, such as fat-raml. This version contains a directory called exchange_modules with all the dependencies declared in the publication form.
RAML
This example creates an asset of type RAML
.
Download the file used in this example here.
Replace /file-path/training-american-flights-api-1.0.0-raml.zip
with the local path of the downloaded file.
organizationId
groupId
assetId
version
name
description
apiVersion
Change the field mainFile
only if another file is uploaded.
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'name=RAML asset name' \
-F 'description=Description of the asset' \
-F 'keywords=this, is, the, best, raml' \
-F 'properties.mainFile=american-flights-api.raml' \
-F 'properties.apiVersion=v1' \
-F 'files.raml.zip=@/file-path/training-american-flights-api-1.0.0-raml.zip' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier raml
and zip
packaging. You may instead upload a single file with packaging .raml
and the type
specified.
RAML Fragment
This example creates an asset of type RAML Fragment
.
Download the file used in this example here.
Replace /Users/llucas/Downloads/training-oauth20-security-scheme-1.0.2-raml-fragment.zip
with the local path of the downloaded file.
Change these fields:
organizationId
groupId
assetId
version
description
name
Change the field mainFile
only if another file is uploaded.
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'name=RAML Fragment asset name' \
-F 'description=Description of the asset' \
-F 'properties.mainFile=OAuth2.raml' \
-F 'files.raml-fragment.zip=@/file-path/training-oauth20-security-scheme-1.0.2-raml-fragment.zip' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier raml-fragment
and zip
packaging. You may instead upload a single file with packaging .raml
and the type
specified.
RAML and RAML Fragment Dependencies
Creating a RAML or RAML Fragment with dependencies requires these additional steps.
Replace GROUP_ID
, ASSET_ID
and VERSION
with the groupId, assetId, and version of each dependency.
- For each dependency, add the dependency property in the multipart form data.Example:
-F 'properties.dependencies=GROUP_ID:ASSET_ID:VERSION
- Download each dependency RAML from Anypoint.
- Place each dependency's content in a folder with the folder structure
exchange_modules/GROUP_ID/ASSET_ID/VERSION/all_the_content
.all_the_content
is the decompressed content of the dependency. - Create a zip file with the
exchange_modules
folder and the content of the RAML or RAML fragment to upload. - Upload the zip file using the multipart form data as described in the examples.Use the name
files.raml.zip
for a RAML asset orfiles.raml-fragment.zip
for a RAML fragment.
When a RAML or RAML fragment is published, the original zip file is modified and a new zip file is created as described in the previous section Fat Package Generation.
OAS API (Swagger)
This example creates an asset of type OAS
.
Download the file used in this example here.
Replace /Users/llucas/Downloads/verato-1.0.0-oas.zip
with the local path of the downloaded file.
Change these fields:
organizationId
groupId
assetId
version
name
description
apiVersion
Change the field mainFile
only if another file is uploaded.
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'name=OAS asset name' \
-F 'description=Description of the asset' \
-F 'properties.mainFile=verato.json' \
-F 'properties.apiVersion=v1' \
-F 'files.oas.zip=@/file-path/verato-1.0.0-oas.zip' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier oas
and zip
packaging. You may instead upload a single oas
file with packaging .oas
.
When an OAS is published, the original zip file is modified and a new zip file is created as described in the previous section Fat Package Generation.
SOAP API (WSDL)
This example creates an asset of type WSDL
.
Change these fields:
organizationId
groupId
assetId
version
name
mainFile
(if a file is uploaded)assetLink
(if no file is uploaded)apiVersion
To create a WSDL by specifying an asset file:
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'name=WSDL asset name' \
-F 'description=The wsdl v2' \
-F 'properties.apiVersion=v1' \
-F 'properties.mainFile=main.wsdl' \
-F 'files.wsdl.zip=@/file-path/wsdl.zip' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier wsdl
and zip
packaging. You may instead upload a single wsdl
file with packaging .wsdl
.
To create a WSDL by specifying an asset link:
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'name=WSDL asset name' \
-F 'description=Description of the asset' \
-F 'type=soap-api' \
-F 'properties.apiVersion=v1' \
-F 'properties.assetLink=http://my-wsdl-api.com' \ https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: When using an asset link, the type cannot be inferred, so we define the asset type
.
Custom
This example creates an asset of type Custom
.
Download the file used in this example here.
Replace /file-path/library.jar
with the local path of the downloaded file.
Change these fields:
organizationId
groupId
assetId
version
name
description
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'name=custom asset name' \
-F 'description=Description of the asset' \
-F 'type=custom' \
-F files.custom.zip=@/file-path/library.jar \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier custom
and zip
packaging.
Note: When the asset type is "Custom", uploading a file is optional.
HTTP API
This example creates an asset of type HTTP
.
Increase the major version for each new version of an HTTP API. For example, increase from 1.0.0
to 2.0.0
.
Change these fields:
organizationId
groupId
assetId
version
name
description
assetLink
apiVersion
Note: The type field is specified because it can not be inferred from a file classifier.
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'name=http asset name' \
-F 'description=Description of the asset' \
-F 'type=http-api' \
-F 'properties.assetLink=http://www.my-http-api-url.com' \
-F 'properties.apiVersion=v3' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
API Group
To create an API Group from API Manager, see the API Manager documentation page API Groups.
Note: The previous examples show how to upload assets of type RAML, RAML Fragment, OAS, WSDL, HTTP API and Custom. The rest of the asset types are uploaded similarly.
Upload an Asset with Properties in a POM File
A POM file is an xml file named pom.xml
or just .pom
with this structure:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>YOUR_GROUP_ID</groupId>
<artifactId>YOUR_ASSET_ID</artifactId>
<version>YOUR_VERSION</version>
<name>The asset name</name>
<description>The asset description</description>
<properties>
<keywords>these, are, keywords, to, be, indexed</keywords>
<mainFile>api.raml</mainFile>
</properties>
<dependencies>
<dependency>
<groupId>DEPENDENCY_GROUP_ID</groupId>
<artifactId>DEPENDENCY_ASSET_ID</artifactId>
<version>DEPENDENCY_VERSION</version>
</dependency>
</dependencies>
</project>
The groupId
, artifactId
(assetId) and version
represent the asset that will be uploaded.
The properties of the asset, including keywords
, are placed inside the properties
tag. In the previous example, mainFile
is specified inside the properties
tag.
If a file is uploaded and the type
can be inferred from the file’s classifier, then it is not necessary to specify the type
property.
Only some assets require defining the <dependencies>
field.
After creating the POM file, upload the POM file and the asset file in a request like this:
curl -v
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-F 'files.mule-application.jar=@/file-path/mule-app.jar' \
-F 'files.pom=@/file-path/mule-app.pom' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
The main file is files.mule-application.jar
, with the classifier mule-application
and the packaging jar
. The pom file is files.pom
, with only the packaging pom
.
Important: The POM groupId, assetId, and version parameters must match the URL path parameters.
The following examples show how to upload an asset with a POM file, including an OAS asset, a Connector asset, and a Mule application asset. Connector assets are typically uploaded by Maven.
OAS
Create the POM file (pom.xml
). Replace the :groupId
, :assetId
, :version
, name
, description
, apiVersion
, and mainFile
.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>:groupId</groupId>
<artifactId>:assetId</artifactId>
<version>:version</version>
<name>oas name</name>
<description>The asset description</description>
<properties>
<apiVersion>v1</apiVersion>
<mainFile>verato.json</mainFile>
</properties>
</project>
For this example, download this OAS file here.
Replace /file-path/verato-1.0.0-oas.zip
with the local path where the file has been downloaded.
Replace /file-path/pom.xml
with the local path of the created pom.xml file.
Replace the :organizationId
, :groupId
, :assetId
, and :version
.
Execute the request.
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'files.pom.xml=@/file-path/pom.xml' \
-F 'files.oas.zip=@/file-path/verato-1.0.0-oas.zip' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier oas and _
zip_ packaging.
files.pomidentifies the POM file. Alternatively, you may use
files.pom.xml`.__
Connector
This asset type requires a POM file and a JAR file to be uploaded. If a POM file is not uploaded, the multipart form data properties must be defined. The POM file will be automatically generated with those properties.
Create the POM file:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>:groupId</groupId>
<artifactId>:assetId</artifactId>
<version>:version</version>
<name>connector name</name>
<description>connector description</description>
</project>
Important: Defining this POM will create the asset, but the connector will work only if the correct dependencies and properties are set. For this case, the real POM can be obtained here and can be used ONLY as a reference.
Download the JAR file used in this example here.
Replace /file-path/mule-salesforce-connector-10.4.1-mule-plugin.jar
with the local path of the downloaded JAR file.
Replace /file-path/pom.xml
with the local path of the created pom.xml file.
Replace the :organizationId
, :groupId
, :assetId
, and :version
.
Execute the request.
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'files.pom=@/file-path/pom.xml' \
-F 'files.mule-plugin.jar=@/file-path/mule-salesforce-connector-10.4.1-mule-plugin.jar' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier mule-plugin
and jar
packaging. files.pom
identifies the POM file. Alternatively, you may use files.pom.xml
.
Mule Application
This asset type requires a POM file and a JAR file to be uploaded. If a POM file is not uploaded, the multipart form data properties must be defined. The POM file will be automatically generated with those properties.
Create the POM file:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>:groupId</groupId>
<artifactId>:assetId</artifactId>
<version>:version</version>
<name>mule application name</name>
<description>asset description</description>
</project>
Important: Defining this POM will create the asset, but the mule application will work only if the correct dependencies and properties are set. In this case, the real POM can be obtained here and can be used ONLY as a reference.
Download the JAR file used in this example here.
Replace /file-path/munit-integration-tests-2.0.1-mule-application.jar
with the local path of the downloaded JAR file.
Replace /file-path/pom.xml
with the local path of the created pom.xml file. Replace the asset file path.
Replace the :organizationId
, :groupId
, :assetId
, and :version
.
Execute the request.
curl -v \
-H 'Authorization: bearer ANYPOINT_TOKEN' \
-H 'x-sync-publication: true' \
-F 'files.pom=@/file-path/pom.xml' \
-F 'files.mule-application.jar=@/file-path/munit-integration-tests-2.0.1-mule-application.jar' \
https://anypoint.mulesoft.com/exchange/api/v2/organizations/:organizationId/assets/:groupId/:assetId/:version
Note: This example uploads a file with classifier mule-application
and jar
packaging. files.pom
identifies the POM file. Alternatively, you may use files.pom.xml
.
Note: Many of these assets are commonly uploaded by Maven, such as Connectors, Examples, Templates, Mule Applications, and Policies. The POM file to upload these assets is the same POM file that is usually uploaded by Maven.