Contact Us 1-800-596-4880
  1. Homepage
  2. Exchange
  3. Autocatalog APIs Using API Catalog CLI

  4. Publish Assets Using API Catalog CLI

Publishing Assets Using API Catalog CLI

You can use the api-catalog publish-asset command to publish your API definitions to Exchange. Embed this command in your automation tools, such as a CI/CD pipeline or custom scripts, to automatically trigger the cataloging of your API assets. The command publishes your API definitions using the information in the file specified in the --descriptor-file option.

Before You Begin

Create a descriptor file that describes the API definitions to publish and copy the file to the file path where your API projects are stored. See Create a Descriptor File Using the CLI.

To publish an API definition using the CLI:

  • Run the api-catalog publish-asset command. The following example publishes API definitions described in the catalog.yaml file:

    > api-catalog publish-asset -d catalog.yaml --host=anypoint.mulesoft.com --organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount --password=myPwd@4!myacct

The following sections give example commands that show how several catalog flags are used:

api-catalog publish-asset

> api-catalog publish-asset [flags]

This command accepts the general and authentication flags in addition to the following flags:

Flag Description

--async

Runs the publish job asynchronously.

-d, --descriptor-file=descriptor-file

or

ANYPOINT_DESCRIPTOR_FILE environment variable

Default: ./catalog.yaml

The name and location of the catalog descriptor file.

  • If the file does not exist, no assets are cataloged.

  • If the file exists but is empty, the command creates and prints the catalog descriptor YAML results. It outputs cataloging information for all API definitions it finds in the full directory tree relative to the current working directory.

  • If a valid YAML file exists, the command catalogs the assets as specified.

See Create a Descriptor File Using the CLI.

--dry-run

Runs the command to verify that the descriptor file is valid. No APIs are published.

--force-publish

Bypasses the comparison and creates a new version of the asset in Exchange regardless of the content.

--force-update-metadata

Updates the asset’s metadata, such as tags, in the latest version in Exchange regardless of the content. This does not republish the asset.

--json

Prints the execution result in JSON format.

-s, --silent

Enables silent logging.

-t, --trigger-criteria=<descriptor-tag>:<value> --trigger-criteria=<descriptor-tag>:value

This flag works in conjunction with the triggerConditions section in the descriptor file. For each run of the api-catalog publish-asset command, the trigger values are compared to trigger condition values in the descriptor file to determine whether to publish the APIs described in the descriptor file. To match multiple conditions, specify separate --trigger-criteria flags for each condition. For the APIs to be published, all trigger conditions set in the descriptor file must be matched by --trigger-criteria flag values.

Example:

--trigger-criteria=branch:main --trigger-criteria=anytag:release/ --trigger=user:admin

See Descriptor YAML Schema.

-v, --verbose

Enables verbose logging.

--version-strategy-criteria=<descriptor-tag>:<value> --version-strategy-criteria=<descriptor-tag>:<value>

This flag works in conjunction with the versionStrategyConditions section in the descriptor file. The api-catalog publish-asset command compares the version strategy criteria values to version strategy condition values in the descriptor file to determine the version strategy to use to publish the APIs. To match multiple conditions, specify separate --version-strategy-criteria flags for each condition.

Example:

--version-strategy-criteria=branch:main --version-strategy-criteria=anytag:release/ --version-strategy-criteria=user:admin

See Descriptor YAML Schema.

Publish an Asset with Default Settings

The following example publishes the API to an organization in the US control plane for Anypoint Platform. Defaults, credentials configuration file settings, or environment variable settings are used for the unspecified flags.

> api-catalog publish-asset --organization 1234abc-b34a-7cd3-4s32-12345abc2345

Perform a Dry Run to Validate the Descriptor File

This example shows the api-catalog publish-asset command with the following flags:

  • --dry-run: Runs the command to verify that the descriptor file is valid but does not publish the APIs.

  • --verbose: Shows the maximum information in the results.

The example command sends the standard output to mycatdryrun.log.

> api-catalog publish-asset --host=anypoint.mulesoft.com -d catalog.yaml --organization=1234abc-b34a-7cd3-4s32-12345abc2345 --client_id=1787c36ab544466698e380131040faad --client_secret=2dA616efca1E4181A2A77BBF046868BE --dry-run --verbose >> mycatdryrun.log

Publish an Asset Regardless of the Content

To publish a new version of the asset in Exchange regardless of the content, use the --force-publish flag.

This example shows the api-catalog publish-asset command with both of these flags. Defaults, credentials configuration file settings, or environment variable settings are used for the unspecified flags.

> api-catalog publish-asset --host=anypoint.mulesoft.com --descriptor-file=mydescriptor.yaml --organization=1234abc-b34a-7cd3-4s32-12345abc2345 --force-publish

Trigger the Publish Using Conditions

Custom trigger conditions enable you to control whether APIs are published when the API Catalog publish-assets runs as part of your CI/CD pipeline or scripts. This example shows how --trigger-criteria flags correlate with descriptor file trigger conditions to control whether or not to publish the described APIs. If a trigger condition is set at the API level, that setting overrides conditions set at the global level.

Example Trigger Conditions in a Descriptor file

Following is an example triggerConditions section in the mydescriptor.yaml descriptor file at the global level:

triggerConditions:
 ref:
  - main
 tags:
  - migrate
  - republish
 status:
  - complete
  - ready

Example That Triggers the Publish

The following command triggers the API publish because the trigger option values match all of the global trigger conditions in the mydescriptor.yaml descriptor file.

> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml --organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount --password=myPwd@4!myacct --trigger-criteria=ref:main --trigger-criteria=tags:migrate --trigger-criteria=status:complete

Example That Does Not Trigger the Publish

The following command does not trigger the API publish because the trigger option value for ref is test, not main. Because not all trigger values match the corresponding global trigger conditions, no APIs are published.

> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml --organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount --password=myPwd@4!myacct --trigger-criteria=ref:test --trigger-criteria=tags:migrate --trigger-criteria=status:complete

Set Version Strategy Using Conditions

Version strategy conditions enable you to set the version of assets when the API Catalog publish-asset command runs as part of your CI/CD pipeline or scripts. This example shows how --version-strategy-criteria flags correlate with descriptor file version strategy conditions to set the version strategy for the described APIs. If a version strategy condition is set at the API level, that setting overrides conditions set at the global level. If the value for a condition matches more than one version strategy, the command gives an error.

Example Version Strategy Conditions in a Descriptor File

Following is an example versionStrategyConditions section in the mydescriptor.yaml descriptor file.

versionStrategyConditions:
patchIncrease:
branch:
 ‘main’
author:
 ‘admin’
snapshot:
branch:
‘test’
‘Develop’

Example That Sets the Version Strategy During the Publish

The following command sets multiple version strategies during the publish because the option values match multiple conditions in the mydescriptor.yaml descriptor file.

> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml --organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount --password=myPwd@4!myacct --version-strategy-criteria=branch:main --version-strategy-criteria=author:admin --version-strategy-criteria=branch:test --version-strategy-criteria=branch:Develop

The resulting version strategies are:

  • Patch increase for APIs in the main branch with an author of admin.

  • Snapshot for APIs in the test and Develop branches.

Example That Does Not Set the Version Strategy During the Publish

The following command does not set the version strategy during the publish because none of the values match the corresponding conditions. The version strategy defaults to patchIncrease if no versionStrategy tags set other values in the descriptor file.

> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml --organization=1234abc-b34a-7cd3-4s32-12345abc2345 -u myAnyPtAccount -p myPwd@4!myacct ----version-strategy-criteria=branch:abc ----version-strategy-criteria=author:dev ----version-strategy-criteria=branch:xyz ----version-strategy-criteria=branch:pop

For more information on version strategies and version strategy conditions, see Descriptor YAML Schema.

Publish Using a Jenkins Script

This example shows a Jenkins script that runs the api-catalog publish-asset command.

pipeline {
    agent any
    environment {
        ANYPOINT_ORG_ID = '1234abc-b34a-7cd3-4s32-12345abc2345'
        CATALOG_DESCRIPTOR = './descriptor.yaml' (1)
     }
     stages {
        stage('git checkout') {
            steps {
                git url: 'git@github.com:mygitlocation/api-catalog-cli.git'
                // additional checkout tasks
            }
        }
        stage('Build Artifacts') {
            steps {
                 // building
            }
        }
        stage('API Cataloging') {
            steps {
                 withCredentials([
                    usernamePassword(credentialsId: 'my-anypoint-creds',
                    usernameVariable: 'ANYPOINT_USERNAME',
                    passwordVariable: 'ANYPOINT_PASSWORD')
                ]) {
                    sh 'api-catalog-cli publish-asset -d $CATALOG_DESCRIPTOR --organization=$ANYPOINT_ORG_ID --host=anypoint.mulesoft.com/ --trigger-criteria=branch:main' (2)
                }
            }
        }
         stage('Deploy') {
            steps {
                // Any deployment tasks to be performed, here.
            }
        }
    }
1 Defines the organization and descriptor file values
2 Runs the api-catalog publish-asset command to publish APIs found in the main Github branch

See Also