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

  4. Creating or Updating Descriptor Files Using the CLI

Creating or Updating Descriptor Files Using the CLI

Before you run the commands to publish your APIs, you must create a descriptor file that has the information Exchange needs to catalog the APIs. Typically you create the file using the CLI and then update the file manually to set more options to control how the assets are published.

The output descriptor information includes the following for each API:

  • API definition file name

  • Asset ID

  • Asset version

  • API version

Create a Descriptor File

Use the api-catalog create-descriptor command to identify and output the API catalog descriptor YAML results to a designated file. The command outputs cataloging information for all API definitions it finds in the full directory tree relative to the current working directory.

api-catalog create-descriptor

> api-catalog create-descriptor [flags]

This command accepts the following flags:

Flag Description

-d, --file=file

Default: catalog.yaml

The name and location in which to save the generated catalog descriptor file

--external

Generates an exchange.json file for each API described in the descriptor file and adds a reference to each of those in the descriptor file using the ref tag in the projects section

To create 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 create-descriptor command. The following example creates a descriptor file called mydescriptor.yaml in the current path:

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

    Example output that is written to the descriptor file:

    #%Catalog Descriptor 1.0
projects:
 - main: async-spec.json
  assetId: async-api
  version: 2.0.0
  apiVersion: v2
 - main: codat.json
  assetId: codat-api
  version: 1.0.0
  apiVersion: v1
 - main: oas-3-spec.json
  assetId: oas-3-api
  version: 3.0.0
  apiVersion: v3

    If you use the --external flag, an exchange.json file is generated for each of your APIs and the descriptor file has references to each of those as shown in the following example:

    > api-catalog create-descriptor -d mydescriptor.yaml --external

    Example output that is written to the descriptor file:

    #%Catalog Descriptor 1.0
projects:
  - ref: api-spec/async-spec.exchange.json
  - ref: api-spec/codat.exchange.json
  - ref: api-spec/oas-3-spec.exchange.json

The presence and content of the designated descriptor file affects the result of the command as follows:

  • No file or empty file: The command discovers the APIs and writes the results to standard output and to a file named catalog.yaml.

  • Existing file with content: The command fails and shows an error message that says the descriptor file already exists.

You can add documentation pages and images to your APIs by adding a Markdown file in the descriptor. You can visualize the image in the documentation page created for the Exchange Asset.

Example descriptor file:

#%Catalog Descriptor 1.0
projects:
  - main: sources/api.raml
    documentation:
      - Summary: Summary.md
      - Use Cases: Use_Cases.md
    assetId: version-basic-api
    apiVersion: v4
    version: 4.0.0

With the Summary.md file containing a link to an image (.png, .jpg) and a documentation Markdown file:

This is a caching service that can be used to retrieve picklist values from publishers who wish to provide a caching service for their picklist fields.

![muley logo](muleyLogo.png)

[Read all the Use Cases](Use_Cases.md)

The presence and content of the designated descriptor file affect the result of the command as follows:

  • No documentation entry for the referenced file in the descriptor catalog: the link to move between pages in the asset portal doesn’t work.

Update a Descriptor File

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.

This command cannot be used to update descriptor files created using the --external flag.

api-catalog update-descriptor

> api-catalog update-descriptor [flags]

This command accepts the following flag:

Flag Description

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

Default: catalog.yaml

The name and location in which to save the updated catalog descriptor file information

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

The presence and content of the designated descriptor file affects the result of the command as follows:

  • No file or empty file: An error message is shown because the update requires that a valid descriptor file exists.

  • Existing file with content: The command compares the APIs in the directory path to the list of APIs in the descriptor file and updates the descriptor file with new and updated API information.

  • File with ref tags in the projects section: The command gives a parsing error, as the update-descriptor command does not support descriptor files with references to external exchange.json files.

See Also