salesforce Dreamforce On-Demand
Contact Us 1-800-596-4880
  1. Homepage
  2. Anypoint CLI (3.x)

  3. API Governance

CLI for API Governance

Command

Description

governance api evaluate

Evaluates filter criteria to determine which rulesets apply to APIs that meet that criteria

governance api inspect

Inspects an API definition and lists its schemas

governance api validate

Validates an API definition against a specified governance ruleset

governance document

Creates the documentation file for a governance ruleset definition

governance profile create

Creates a governance profile

governance profile delete

Deletes a governance profile

governance profile info

Lists information for a specific governance profile ID

governance profile list

Lists all governance profiles for an organization

governance profile update

Updates a governance profile

governance ruleset clone

Clones a governance ruleset and applies specified updates to rules

governance ruleset info

Lists ruleset rules

governance ruleset init

Initializes a governance ruleset definition based on a data schema

governance ruleset validate

Validates a governance ruleset definition’s format

governance api evaluate

> governance api evaluate [options]

This command evaluates specified filters to determine the rulesets that would be applied to your APIs that meet that criteria.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--api=<api>

The API project against which you want to evaluate. The command uses the criteria in the project’s exchange.json file.

--criteria <filtertype:filtervalue>,…​

Enables you to apply filters against which to evaluate to identify rulesets. Specify a list of comma-separated filters where each filter has a type and value, in the format filtertype:filtervalue.

Available filters include:

  • scope: API type, rest-api or async-api

  • tag: Tag defined for APIs in Exchange

  • category: Category defined for APIs in Exchange, where the filter value is specified in two parts as categoryName:value

  • status: Lifecycle state of stable, development, or deprecated

  • env-type: Environment type of any, production, or sandbox

  • env-id: The ID for the environment name in API Manager. You can get this value using API Manager > Environment information. See Reviewing Environment Concepts.

    If env-type or env-id is used, the API Instance filter is set in the profile, so that only APIs that have instances are filtered. APIs in the development lifecycle cannot have instances.

    To deselect the API Instance filter in the profile using the CLI, update the profile using the --criteria flag with neither env-type nor env-id.

Example: tag:tag1,category:category1:value,category:category2:value2,status:stable,status:development,status:deprecated,scope:rest-api,scope:async-api,env-type:production
This command must be run with either the criteria or the api option.

Example commands:

anypoint-cli governance api evaluate --criteria `tag:best,category:API Type:Experience API,scope:rest-api`

anypoint-cli governance api evaluate --api ~/Downloads/order-api-1.0.0-raml.zip

Example output:

Ruleset GAV
68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/1.0.0
8a840abd-e63a-4f8b-87ab-24052eda2017/best-practices-ruleset/1.0.0
68ef9520-24e9-4cf2-b2f5-620025690913/required-examples/1.0.0

governance api inspect

> governance api inspect [options] <api-definition>

This command inspects the API definition passed in api-definition and lists all its schemas, such as headers, requests, and response payloads. You can use this schema information in the governance ruleset init command. See governance ruleset init.

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example command:

anypoint-cli governance api inspect my-healthcare-api.yaml

Example schema

types:
  patientmultipleBirthBoolean:
    properties:
      multipleBirthBoolean:
        description: Whether patient is part of a multiple birth
        type: boolean
  patientmultipleBirthInteger:
    properties:
      multipleBirthInteger:
        description: Whether patient is part of a multiple birth
        type: integer

        .
        .
        .

  PatientEntry:
    type: FHIR_commons.Entry
    properties:
      resource: Patient

  PatientBundle:
    type: FHIR_commons.Bundle
    properties:
      entry?: PatientEntry[]

Example output:

  'patientmultipleBirthBoolean',
  'PatientBundle',
  'patientmultipleBirthInteger',
  'PatientEntry'

governance api validate

> governance api validate [options] <api-definition>

This command validates the API definition passed in api-definition against specified rulesets.

You can specify api-definition as one of the following:

  • An API project ZIP file

  • An API project folder

  • An asset identifier for an API project, if the --remote option is specified. An asset identifier is a group ID, asset ID, and version (GAV) that uniquely identifies each asset in Exchange.

You can specify rulesets against which to validate as follows:

  • To use an existing exchange.json file that defines your API project’s ruleset dependencies, ensure that it is included in the folder or ZIP file that you specify in api-definition. If the exchange.json file is present, the command downloads all dependencies and validates against the rulesets in the project.

  • To validate directly against rulesets published in Exchange, use the --remote-rulesets option.

  • To validate against local rulesets, use the --rulesets option.

Duplicate rulesets are not detected, so if you use more than one of the preceding ways of identifying rulesets in the same command execution, some rulesets may be validated multiple times.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--rulesets <ruleset-yaml-file1>,<ruleset-yaml-file2>,…​

Local ruleset definitions. The rulesets option is followed by a comma-separated list of ruleset YAML files.

--remote-rulesets <ruleset-asset-identifier>,<ruleset-asset-identifier>,…​

Remote ruleset definitions. The remote-rulesets option is followed by a comma-separated list of ruleset asset identifiers. An asset identifier is a group ID, asset ID, and version (GAV) that uniquely identifies each asset in Exchange. For example: <group_id>/<asset_id>/<version>,<group_id>/<asset_id>/<version>

See Get Exchange Asset Identifiers (GAVs).

--remote

Flag to indicate that the validation should be done against a published API. The value passed in api-definition is the API’s asset identifier. An asset identifier is a group ID, asset ID, and version (GAV) that uniquely identifies each asset in Exchange. For example: <group_id>/<asset_id>/<version>

See Get Exchange Asset Identifiers (GAVs).

Example commands:

anypoint-cli governance api validate ~/Downloads/order-api-1.0.0-raml.zip

anypoint-cli governance api validate ~/Downloads/order-api-1.0.0-raml

anypoint-cli governance api validate --rulesets /MyRulesets/ruleset1.yaml,/MyRulesets/ruleset2.yaml  ~/Downloads/order-api-1.0.0-raml.zip

anypoint-cli governance api validate --remote-rulesets 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1  ~/Downloads/order-api-1.0.0-raml.zip

anypoint-cli governance api validate --remote-rulesets 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1 --remote 8a840abd-e63a-4f8b-87ab-24052eda2017/order-api/1.0.0

Example output:

For a definition that is conformant to the ruleset:

 Spec conforms with Ruleset

For a definition that is nonconformant to the ruleset:

Conforms: false
Number of results: 3 (1)

Functional Validations
----------------------

Constraint: http://a.ml/vocabularies/amf/core#declaration-not-found
Severity: Violation
Message: not supported scalar for documentation
Target: null
Range: [(6,3)-(6,3)]
Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml

Conformance Validations (2)
-----------------------

Constraint: file:///exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/1.0.0/ruleset.yaml#/encodes/validations/api-must-have-documentation (3)
Severity: Warning (4)
Message: Provide the documentation for the API. (5)
Target: amf://id#2 (6)
Range: [(2,0)-(6,4)] (7)
Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml (8)

Constraint: file:///exchange_modules/8a840abd-e63a-4f8b-87ab-24052eda2017/best-practices-ruleset/1.0.0/bestpractices.yaml#/encodes/validations/api-must-have-documentation
Severity: Violation
Message: Provide the documentation for the API
Target: amf://id#2
Range: [(2,0)-(6,4)]
Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml
1 Total of functional and conformance validation issues found
2 Conformance issues section
3 Ruleset and rule to which this set of issues applies
4 Severity level for the issue
5 Description of the issue
6 AMF model node ID; for information on the AMF model, see Creating Custom Governance Rulesets
7 Beginning line number and column and end line number and column in the API definition where the issue occurs, where column is the offset from the beginning of the line and numbering for the offset starts at 0
8 The file in which the issue occurs, either the main file or one of its dependencies

governance document

> governance document [options] <ruleset> <doc-file>

This command creates the documentation for the API Governance ruleset definition ZIP file specified in ruleset. It puts the documentation in the doc-file ZIP file for you to upload and publish to Exchange.

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example command:

anypoint-cli governance document ~/temp/ruleset.yaml ~/temp/ruleset.doc.zip

Example output:

 validation name [ 'scalar-parameters' ]
 Saving to /Users/janedoe/temp/prof-1.doc.zip

governance profile create

> governance profile create [options] <profile-name> <ruleset-asset-identifiers>

This command creates a governance profile using a string value for the new governance profile name specified in profile-name.

You must include ruleset-asset-identifiers, a comma-separated list of ruleset asset identifiers, each of which is the group ID, asset ID, and version (GAV) that uniquely identifies each asset in Exchange. For example: <group_id>/<asset_id>/<version>,<group_id>/<asset_id>/<version>, where <version> is a specific version or latest. If you use latest as the version, the profile automatically uses the latest version of the ruleset when versions are published after you create the profile.

You can use one of the notify options to configure notifications for the profile you are creating. If you do not use a notify option, no notifications are configured by the command. Notifications are off by default.

See Get Exchange Asset Identifiers (GAVs).

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--criteria <filtertype:filtervalue>,…​

Enables you to apply filters to select the list of APIs to which the profile rulesets will apply. Specify a list of comma-separated filters where each filter has a type and value in the format filtertype:filtervalue.

Available filters include:

  • scope: API type, rest-api or async-api

  • tag: Tag defined for APIs in Exchange

  • category: Category defined for APIs in Exchange, where the filter value is specified in two parts as categoryName:value

  • status: Lifecycle state of stable, development, or deprecated

  • env-type: Environment type of any, production, or sandbox

  • env-id: The ID for the environment name in API Manager. You can get this value using API Manager > Environment information. See Reviewing Environment Concepts.

    If env-type or env-id is used, the API Instance filter is set in the profile, so that only APIs that have instances are filtered. APIs in the development lifecycle cannot have instances.

    To deselect the API Instance filter in the profile using the CLI, update the profile using the --criteria flag with neither env-type nor env-id.

Example: tag:tag1,category:category1:value,category:category2:value2,status:stable,status:development,status:deprecated,scope:rest-api,scope:async-api,env-type:production

--tags <tags> Deprecated

The --criteria option replaces the tags option starting with Anypoint CLI version v3.17.0. In versions prior to v3.17.0, the tags option is followed by a comma separated list of tags to be applied to the new governance profile, formatted as follows: tag1,tag2,tag3

--description <description>

The description option is followed by a string that is the new governance profile’s description.

--notify-contact

Enables notifications and sets the recipient to the contact set for the API.

--notify-publisher

Enables notifications and sets the recipient to the API publisher.

--notify-others <email ID,email ID,…​>

Enables notifications and sets the recipient to the specified list of email IDs.

Example commands:

anypoint-cli governance profile create "Open API Best Practices" 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1 --criteria "tag:oas,category:API Type:Experience API,status:development,scope:rest-api" --description "Profile for OAS Best Practices"

anypoint-cli governance profile create "Anypoint Best Practices" 68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-api-best-practices/1.0.1 --criteria "tag:raml tag:oas category:API Type:Experience API,status:stable,scope:rest-api" --description "Profile for REST API Best Practices" --notify-publisher  --notify-contact --notify-others a@a.a,b@b.com

anypoint-cli governance profile create "Primary API Standards" 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/latest,68ef9520-24e9-4cf2-b2f5-620025690913/myorg-best-practices/1.0.2 --criteria "tag:prim,category:API Type:Experience API,status:stable,scope:rest-api,env-id:0683ce02-cd53-4028-a543-832a38a8af30" --description "Profile for Primary API Standards"

Example output:

 Profile Added
 Id         	4f98e59d-8efb-420f-ac95-9cd0af15bd45
 Name       	OAS Best Practices
 Description	Profile for OAS Best Practices
 Rulesets   	gav://68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1
 Filter     	tag:best

governance profile delete

> governance profile delete [options] <profile-id>

This command deletes a specific governance profile specified by profile-id. To get this ID, run the governance profile info or governance profile list command.

The governance profile delete command accepts only the default options: --help, -f/--fields and -o/--output.

Example command:

anypoint-cli governance profile delete 8ffd463f-86b2-4132-afc6-44d179209362

Example output:

 Profile with id 8ffd463f-86b2-4132-afc6-44d179209362 removed

governance profile info

> governance profile info [options] <profile-id>

This command lists all information for a governance profile ID.

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example command:

anypoint-cli governance profile info 19fb211b-8775-43cc-865a-46228921d6ed --output text

Example output:

Id         	        19fb211b-8775-43cc-865a-46228921d6ed
Name       	        Best Practices
Description	        Best Practices Profile
Rulesets   	        68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/1.0.0 8a840abd-e63a-4f8b-87ab-24052eda2017/best-practices-ruleset/1.0.0 68ef9520-24e9-4cf2-b2f5-620025690913/required-examples/1.0.0
Criteria   	        tag:best,category:API Type:Experience API,scope:rest-api
NotificationConfig  Contact,Publisher

governance profile list

> governance profile list [options]

This command lists information for all governance profiles for an organization. You need this information when updating a governance profile.

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example command:

anypoint-cli governance profile list -o text

Example output:

Profile Name                 	Profile Id

Minimum Security Requirements	1f418cf4-b870-4b31-8734-f55f28d45f8f
Best Practices               	19fb211b-8775-43cc-865a-46228921d6ed
New Best Practices           	4eaf9176-3ef9-4021-a67c-6e4bc10d3763
OAS Standards                	51ae8795-2278-407e-942f-becba29af986

governance profile update

> governance profile update [options] <profile-id>

This command updates the governance profile specified in profile-id. To get this ID, run the governance profile info or governance profile list command.

You can update the governance profile’s general information, rulesets, filter criteria, and notification configuration. You can use one of the notify options to update the notification configuration or turn off notifications. Any changes override existing notification configurations. If you do not use a notify option, no changes are made to the notification configuration.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--profile-name <profile-name>

The profile-name option is followed by a string that is the new governance profile name.

--ruleset-gavs <ruleset-gavs>

The ruleset-gavs option is a list with the asset identifier for each ruleset, formatted as follows: <group_id>/<asset_id>/<version>,<group_id>/<asset_id>/<version>, where <version> is a specific version or latest. An asset identifier is a unique group ID, asset ID, and version (GAV) that identifies each asset in Exchange. If you use latest as the version, the profile automatically uses the latest version of the ruleset when versions are published after you create the profile.

See Get Exchange Asset Identifiers (GAVs).

--criteria <filtertype:filtervalue>,…​

Enables you to apply filters to select the list of APIs to which the profile rulesets will apply. Specify a list of comma-separated filters where each filter has a type and value in the format filtertype:filtervalue.

Available filters include:

  • scope: API type, rest-api or async-api

  • tag: Tag defined for APIs in Exchange

  • category: Category defined for APIs in Exchange, where the filter value is specified in two parts as categoryName:value

  • status: Lifecycle state of stable, development, or deprecated

  • env-type: Environment type of any, production, or sandbox

  • env-id: The ID for the environment name in API Manager. You can get this value using API Manager > Environment information. See Reviewing Environment Concepts.

    If env-type or env-id is used, the API Instance filter is set in the profile, so that only APIs that have instances are filtered. APIs in the development lifecycle cannot have instances.

    To deselect the API Instance filter in the profile using the CLI, update the profile using the --criteria flag with neither env-type nor env-id.

Example: tag:tag1,category:category1:value,category:category2:value2,status:stable,status:development,status:deprecated,scope:rest-api,scope:async-api,env-type:production

--tags <tags> Deprecated

The --criteria option replaces the tags option starting with Anypoint CLI version v3.17.0. In versions prior to v3.17.0, the tags option is followed by a comma separated list of tags to be applied to the new governance profile, formatted as follows: tag1,tag2,tag3

--description <description>

The description option is followed by a string that is the new governance profile description.

--notify-off

Disables notifications.

--notify-contact

Enables notifications and sets the recipient to the contact set for the API.

--notify-publisher

Enables notifications and sets the recipient to the API publisher.

--notify-others <email ID,email ID,…​>

Enables notifications and sets the recipient to the specified list of email IDs.

Example commands:

anypoint-cli governance profile update 4eaf9176-3ef9-4021-a67c-6e4bc10d3763 --profile-name "MyOrg Best Practices"

anypoint-cli governance profile update 19fb211b-8775-43cc-865a-46228921d6ed --criteria `tag:best,category:API Type:Experience API,status:development,scope:rest-api`

anypoint-cli governance profile update 67eff44a-28a3-43d4-93d9-bddedb92c711 --notify-publisher  --notify-contact --notify-others a@a.a,b@b.com

anypoint-cli governance profile update 67eff44a-28a3-43d4-93d9-bddedb92c711 --notify-off

anypoint-cli governance profile update 19fb211b-8775-43cc-865a-46228921d6ed --criteria `tag:best,category:API Type:Experience API,status:production,scope:rest-api,env-type:production` --ruleset-gavs 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/latest,68ef9520-24e9-4cf2-b2f5-620025690913/myorg-best-practices/latest

Example output:

 Profile updated 51f9f94c-fb0c-43d4-9895-22c9e64f1537

Limitations

You cannot configure notifications using the governance profile update command. After you create a profile using the CLI, you can configure notifications by editing the profile in the API Governance console. See Update a Governance Profile Using the API Governance Console.

governance ruleset clone

> governance ruleset clone [options] <ruleset> <new_title> <new_description>

This command clones a governance ruleset to create a new custom ruleset and applies specified updates to rules based on the options. The new ruleset is written to standard output.

The new-title parameter gives the title for the new ruleset.

The new description parameter gives the description for the new ruleset.

Run the governance ruleset info command before running this command to get the rule ID information to use in this command.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--remote

Indicates that the ruleset to clone is published in Exchange and that the ruleset parameter is the asset identifier for the ruleset. An asset identifier is the group ID, asset ID, and version (GAV) that uniquely identifies each asset in Exchange. For example: <group_id>/<asset_id>/<version>

See Get Exchange Asset Identifiers (GAVs).

--error=<list_rules_to_move_to_error>

The error option is followed by the rule IDs for the rules to move to the error severity level section of the ruleset YAML.

--warning=<list_rules_to_move_to_warning>

The warning option is followed by the rule IDs for the rules to move to the warning severity level section of the ruleset YAML.

--info=<list_rules_to_move_to_info>

The info option is followed by the rule IDs for the rules to move to the info severity level section of the ruleset YAML.

--remove=<list_rules_to_disable>

The remove option is followed by the rule IDs for the rules to comment out, and therefore effectively disable, in the ruleset YAML.

Example commands:

anypoint-cli governance ruleset clone ~/Downloads/ruleset.yaml 'New Ruleset from Clone' 'Cloned from ruleset.yaml' --warning=operation-default-response,operation-operationId > mynewruleset.yaml

anypoint-cli governance ruleset clone 68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/1.0.2 'Custom Anypoint Best Practices' 'Cloned from MuleSoft Anypoint Best Practices' --remote --remove=openapi-tags,operation-tags > my-anypoint-best-practices.yaml

governance ruleset info

> governance ruleset info [options] <governance-ruleset>

This command lists the ruleset rules in the ruleset definition passed in the governance-ruleset parameter.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--remote

Indicates that the ruleset for which to get information is published in Exchange and that the ruleset parameter is the asset identifier for the ruleset. An asset identifier is the group ID, asset ID, and version (GAV) that uniquely identifies an asset in Exchange. For example: <group_id>/<asset_id>/<version>, where <version> is a specific version or latest. If you use latest as the version, the profile automatically uses the latest version of the ruleset when versions are published after you create the profile.

See Get Exchange Asset Identifiers (GAVs).

Example commands:

anypoint-cli governance ruleset info ~/temp/myruleset.yaml

anypoint-cli governance ruleset info 68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/1.0.2 --remote

anypoint-cli governance ruleset info 68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/latest --remote

Example output:

Ruleset /Users/myuser/temp/myruleset.yaml
Violation	operation-default-response
Violation	operation-operationId
Warning  	operation-singular-tag
Warning  	tag-description
Warning  	info-contact
Warning  	info-description
Warning  	info-license
Warning  	license-url
Warning  	openapi-tags
Warning  	operation-description
Warning  	operation-tags
Warning  	operation-tag-defined

governance ruleset init

> governance ruleset init [options] <schema>

This command initializes a ruleset based on the data schema passed in the schema parameter.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--types <types>

The types option gives the target types to export as rules. You can use the governance api inspect command to identify the types to specify in this option. See governance api inspect.

--name <name>

The name option is the name of the ruleset. Defaults to GeneratedRuleset.

Example command:

anypoint-cli governance ruleset init --types patientmultipleBirthBoolean,patientBundle,patientmultipleBirthInteger --name=my-ruleset mydataschema

governance ruleset validate

> governance ruleset validate [options] <governance-ruleset>

This command validates the ruleset definitions passed using the governance-ruleset parameter. You can pass one of the following as the governance-ruleset parameter:

  • A ruleset definition YAML file

  • A ZIP file that contains an API project with an exchange.json file that specifies the ruleset as the main file

  • A folder that contains an API project with an exchange.json file that specifies the ruleset as the main file

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example commands:

anypoint-cli governance ruleset validate ~/temp/myruleset.yaml

anypoint-cli governance ruleset validate ~/temp/myruleset.zip

anypoint-cli governance ruleset validate ~/temp/myrulesetfolder

Example output for a valid ruleset:

 Ruleset conforms with Dialect

Example output for a nonvalid ruleset:

Ruleset does not conform with Dialect
ModelId: file:///Users/janedoe/temp/prof-1-bad.yaml
Profile: Validation Profile 1.0
Conforms: false
Number of results: 1

Level: Violation

- Constraint: http://a.ml/amf/default_document#/declarations/profileNode_profile_required_validation
  Message: Property 'profile' is mandatory
  Severity: Violation
  Target: file:///Users/janedoe/temp/prof-1-bad.yaml#/encodes
  Property: http://schema.org/name
  Range: [(3,0)-(11,19)]
  Location: file:///Users/janedoe/temp/prof-1-bad.yaml

Get Exchange Asset Identifiers (GAVs)

To get the GAVs for Exchange assets:

  • If you are using the Exchange CLI, run the anypoint-cli exchange asset list command.

  • If you are using the Exchange web UI, select the asset in Exchange and then copy the group ID and asset ID from the URL. Add the version node for the version you are viewing. For example, the GAV for the OpenAPI Best Practices ruleset in Exchange is 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1.