api-catalog-cli v1.1.2

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.

Command

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

Example Descriptor File:

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

#%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

Command

USAGE

  $ api-catalog update-descriptor [FLAGS]

FLAGS

  -d, --descriptor-file=<value>  [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.

Publish API Command

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=<value>           [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=<value>...       [default: ] Filters that are applied to the descriptor file to determine whether
                                          an asset should be published.
                                          Format: <name>:<regular expression>
                                          Example: branch:latest
  -v, --verbose                           Enable verbose logging
  --async                                 Run the publish job asynchronously
  --bearer=<value>                        Token Bearer. You can define this in the ANYPOINT_BEARER environment variable.
  --client_id=<value>                     Client ID. You can define this in the ANYPOINT_CLIENT_ID environment variable.
  --client_secret=<value>                 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=<value>                   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=<value>                  (required) Organization Name. You can define this in the ANYPOINT_ORG environment
                                          variable.
  --password=<value>                      Password. You can define this in the ANYPOINT_PASSWORD environment variable.
  --username=<value>                      Username. You can define this in the ANYPOINT_USERNAME environment variable.
  --version-strategy-criteria=<value>...  [default: ] Filters that are applied to the descriptor file to determine the
                                          version strategy of the asset.
                                          Format: <name>:<regular expression>
                                          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