API Catalog CLI

API Catalog CLI enables you to discover and catalog your API definitions, documentation files, and associated metadata as part of an automated process. You can embed the publish asset command in your automation tools, such as a CI/CD pipeline or custom scripts, to automatically trigger the publishing of your API assets to Exchange. API Catalog CLI is agnostic of CI/CD tools and runtime environments.

With API Catalog CLI you can:

* Identify all APIs in a project directory structure and create a descriptor file to use to publish the APIs to Exchange.

* Identify all new and changed APIs and update the descriptor file on an ongoing basis.

* Conditionally trigger the publish based on criteria such as branches and tags.

* Conditionally set the asset version strategy based on criteria such as branches and tags.

* Publish APIs described in the descriptor file by running commands either at a command prompt or as part of your CI/CD pipelines or custom scripts.

To get started with API Catalog CLI:

1. Install API Catalog CLI.

2. Get familiar with the general use of API Catalog, such as how to pass authentication information and how to use the general command flags.

3. Create a descriptor file to identify the APIs to publish.

4. Catalog an asset using API Catalog CLI and view it in Anypoint Exchange.

For more detailed instructions on how to use API Catalog CLI, please refer to the documentation.

View Command Help

Use the help argument with the commands to list the commands or command options and their descriptions:
* api-catalog --help

* api-catalog autocomplete --help

* api-catalog create-descriptor --help

* api-catalog update-descriptor --help

* api-catalog publish-asset --help

Optionally use the api-catalog autocomplete command by following the instructions in the command help.

Create a Descriptor File Using the CLI

You can run the api-catalog create-descriptor command to create and print the catalog descriptor YAML results to a designated file. The command will output cataloging information for all API specifications it finds in the full directory tree relative to the current working directory.

To create a descriptor file:

1. Navigate to the directory path that contains the APIs you want to catalog.

2. Run the api-catalog create-descriptor command. The following example creates a descriptor file called mydescriptor.yaml in the current path:

> api-catalog create-descriptor -f mydescriptor.yaml

You can optionally create a descriptor file manually instead of using the api-catalog create-descriptor command to generate the file. See Create a Descriptor File Manually.

$3

USAGE
``
$ api-catalog create-descriptor [FLAGS]
`
FLAGS
`
-d, --file=file [default: catalog.yaml] The name and directory location to save the generated catalog descriptor
file
--external [default: false] The parameter to create the descriptor file generating an exchange.json file
for each API
`
DESCRIPTION

This command generates a descriptor file by discovering APIs in the current directory

$3

Following is an example descriptor file that describes the cataloging information for two APIs. More information in Descriptor YAML Schema

`yaml
#%Catalog Descriptor 1.0
triggerConditions:
branches:
- main
- release/(.*)
tags:
- support
- release/(.*)
user:
- admin

contact:
name: 'John Doe'
email: 'john.doe@org.com'

projects:
- main: api-spec/codat.json
assetId: codat-api
documentation:
add: api-spec/add.md
home: home.md
customFields:
custom: value
another:
- value_1
- value_2
tags:
- codat
- gcp
version: 2.0.0
versionStrategy: patchIncrease
versionStrategyConditions:
majorIncrease:
tags:
- support
apiVersion: v3

- main: api-spec/billing-api.json
assetId: my-awesome-api
tags:
- finance
- aws
categories:
API Type:
- System API
- Experience API
Organization:
- Finance
- Billing
version: 1.0.0
versionStrategy: minorIncrease
versionStrategyConditions:
majorIncrease:
branches:
- master
apiVersion: v1
`

Update a Descriptor File Using the CLI

Use the api-catalog update-descriptor command to update the API catalog descriptor YAML results in a designated file. The command adds and updates cataloging information for all new and updated API definitions it finds in the full directory tree relative to the current working directory.

To update a descriptor file using the CLI:

1. Navigate to the directory path that contains the APIs you want to catalog.

2. Run the api-catalog update-descriptor command. The following example updates a descriptor file called mydescriptor.yaml in the current path:

> api-catalog update-descriptor -d mydescriptor.yaml

$3


USAGE
`
$ api-catalog update-descriptor [FLAGS]
`
FLAGS
`
-d, --descriptor-file= [default: ./catalog.yaml] The name and location of the catalog descriptor file.
`
DESCRIPTION

Update a descriptor file based on the contents of the current directory

This command updates a given descriptor file by discovering APIs in the current directory


For information on using the api-catalog update-descriptor command, see Update a Descriptor File.

Publish API Using CLI

You can publish your APIs to Anypoint Exchange with API Catalog CLI commands. To automate the publishing of APIs using CLI, you will typically use build scripts in tools such as Jenkins, but you can run the CLI manually from a terminal for learning and testing purposes.

##### Prerequisites

* Create a descriptor file and copy it to the file path where your API projects are stored. See Create a Descriptor File.




$3

This command publishes APIs to Exchange using the YAML descriptor information specified in the --descriptor-file option.

USAGE
`
$ api-catalog publish-asset [FLAGS]
`
FLAGS
`
-d, --descriptor-file= [default: ./catalog.yaml] The name and location of the catalog descriptor file.
You can define this in the ANYPOINT_DESCRIPTOR_FILE environment variable.
-s, --silent enable silent logging
-t, --trigger-criteria=... [default: ] Filters that are applied to the descriptor file to determine whether
an asset should be published.
Format: :
Example: branch:latest
-v, --verbose Enable verbose logging
--async Run the publish job asynchronously
--bearer= Token Bearer. You can define this in the ANYPOINT_BEARER environment variable.
--client_id= Client ID. You can define this in the ANYPOINT_CLIENT_ID environment variable.
--client_secret= Client Secret. You can define this in the ANYPOINT_CLIENT_SECRET environment
variable.
--dry-run Runs the command to verify that the descriptor file is valid. No APIs will be
published
--environment= Environment Name. You can define this in the ANYPOINT_ENV environment variable.
--force-publish 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
--host=anypoint.mulesoft.com [default: anypoint.mulesoft.com] Host URL. You can define this in the
ANYPOINT_HOST environment variable.
--json Prints the execution result in JSON format
--organization= (required) Organization Name. You can define this in the ANYPOINT_ORG environment
variable.
--password= Password. You can define this in the ANYPOINT_PASSWORD environment variable.
--username= Username. You can define this in the ANYPOINT_USERNAME environment variable.
--version-strategy-criteria=... [default: ] Filters that are applied to the descriptor file to determine the
version strategy of the asset.
Format: :
Example: branch:lates


`
DESCRIPTION

This command publishes assets to Anypoint Exchange, extracting information from a specified descriptor file.

Most arguments can be preset in environment variables.

By default, the descriptor file is assumed to be located in ./catalog.yaml.

- If no such file exists, no assets will be cataloged.
- If the file exists but is empty, the command will create and print the catalog descriptor YAML results. It will
output cataloging information for all API specifications it finds in the full directory tree relative to the current
working directory.
- If a valid YAML file exists, the command will catalog the assets as specified.

For more detailed instructions on how to use the descriptor file, please refer to the documentation.

Configure Command Autocompletion

The autocomplete command enables you to configure completion for API Catalog CLI commands. To configure it, run api-catalog autocomplete and follow the instructions.

To display the autocomplete configuration instructions, run:

> api-catalog autocomplete --help


USAGE
`
$ api-catalog autocomplete [SHELL]
`

ARGUMENTS
`
SHELL shell type
`

OPTIONS
`
-r, --refresh-cache Refresh cache (ignores displaying instructions)
`

EXAMPLES
`
$ api-catalog autocomplete
$ api-catalog autocomplete bash
$ api-catalog autocomplete zsh
$ api-catalog autocomplete --refresh-cache
``