Asset Versions

Each asset in Exchange is versioned. You can manage which versions are visible by deprecating a version to hide it, and delete versions if needed. All versions of an asset always have the same type.

APIs also have a consumer-facing API version that appears in an asset’s detail screen. API providers define this version.

Exchange asset versions follow the Semantic Versioning model of major, minor, and patch releases. For example, if an asset is version 2.4.6, then its major version is 2.x.x, its minor version is 2.4.x, and its patch version is 2.4.6.

To select a minor version of an asset, use the menu next to the asset name at the top of the asset portal. To select a patch version of an asset, use the version list at the right.

RAML versions are automatically generated for all OAS assets published since January 12, 2019. OAS 2.0 versions are automatically generated for all RAML assets published since that date.

Choose a Version Number When Publishing

When you publish a new asset version through the API, you can let Exchange determine the next available version number instead of specifying it manually. The nextAvailableVersion endpoint in Exchange API v2 returns the next version number that is free to publish.

Use the versionOrder parameter to control which part of the semantic version increments:

Value Result

Value	Result
`MAJOR`	Returns the next available major version, such as 3.0.0.
`MINOR`	Returns the next available minor version, such as 2.5.0.
`PATCH`	Returns the next available patch version, such as 2.4.7.

MAJOR

Returns the next available major version, such as 3.0.0.

MINOR

Returns the next available minor version, such as 2.5.0.

PATCH

Returns the next available patch version, such as 2.4.7.

All three values are valid for any asset type. REST APIs and SOAP APIs commonly publish major, minor, and patch versions. HTTP APIs and API Groups usually publish only major versions, but the endpoint returns a minor or patch version when you request one explicitly.

Reserved Version Numbers for Deleted Versions

When you soft-delete an asset version, its combination of groupId, assetId, and version (GAV) remains permanently reserved. This behavior applies to every asset type, including API Groups. The nextAvailableVersion endpoint skips reserved version numbers and never reuses them, even though a soft-deleted version no longer appears in the catalog.

To make a specific version number available again, enable GAV reuse and then hard-delete that version. Enabling GAV reuse frees only the version numbers that you hard-delete; it does not free an asset’s entire version history. To free every version number for an asset, delete every version of the asset.

If you republish a version number that belongs to a soft-deleted version, Exchange returns a 409 Conflict response with the message There is a deleted asset with the same version number.

To resolve the conflict, do one of the following:

Use the nextAvailableVersion endpoint to publish at the next free version number.
Manually choose a higher version number that is not reserved.
Enable GAV reuse, hard-delete the conflicting version, and then republish.

Asset Limits

An asset’s version format must use semantic versioning. Asset fields have these length limits:

Field	Maximum Length	Minimum Length
Name	256	1
Description	256	0
`versionGroup`	256	1
Combined `groupId`, `assetId`, and `version`	215	NA

Exchange prevents resource exhaustion attacks by limiting the number of asset versions that can be published. Each version of an asset counts individually toward this limit. For example, an asset published at versions 1.0.0 and 1.0.1 counts as two asset versions. Incomplete asset versions also count toward the limit.

The limit is 500 asset versions for root organizations with trial accounts, and 100,000 (one hundred thousand) asset versions for root organizations with all other account types.

The limit of dependencies for an asset is 100. For example, in Anypoint API Designer a RAML is limited to 100 RAML Fragment dependencies, and in Anypoint API Manager an API Group is limited to 100 REST API dependencies.

This count does not include deleted asset versions or assets generated by Exchange such as REST Connect Connector Generator.

When a root organization reaches 80% of its asset version limit, Exchange shows a warning.

When a root organization reaches its asset version limit, Exchange shows an error. Also, using the Publish new asset button on the home page or the Add new version button on the asset detail page shows an error explaining that the limit is reached and no more asset versions can be added.

Check the limit of your root organization with a curl command like this:

    curl -X GET \
      https://anypoint.mulesoft.com/exchange/api/v1/organizations/ROOT_ORGANIZATION_ID/limits \
      -H 'Authorization: bearer ANYPOINT_TOKEN'

Replace ROOT_ORGANIZATION_ID with your root organization ID, and replace ANYPOINT_TOKEN with the authorization token that has permissions for the root organization.

Get lists of assets with a curl command like this:

    curl -X POST \
      https://anypoint.mulesoft.com/graph/api/v1/graphql \
      -H 'content-type: application/json' \
      -H 'Authorization: bearer ANYPOINT_TOKEN' \
      -d '{"query":"{assets(query: { rootOrganizationId:\"ROOT_ORGANIZATION_ID\", limit: 20, offset: 10 }) {groupId assetId version}}"}'

Replace ROOT_ORGANIZATION_ID with your root organization ID, and replace ANYPOINT_TOKEN with the authorization token that has permissions for the root organization. Vary the limit and offset values as needed.

See Search Using the Graph API for more information about searching for assets.