salesforce Dreamforce On-Demand
Contact Us 1-800-596-4880
  1. Homepage
  2. API Governance

  3. Applying Rulesets to Identified APIs

Applying Rulesets to Identified APIs

After you identify the APIs in Exchange that you want to govern, add your governance profiles. Governance profiles enable you to filter the specific sets of APIs to govern for each set of rulesets. When you create or update a profile, the set of APIs that meet the filter criteria in the profile are validated against the set of rulesets selected in the profile.

Only API Governance and organization administrators can create, edit, and delete profiles.

Create a Governance Profile Using the API Governance Console

The API Governance console UI guides you through creating profiles. You can save a profile as draft to test your settings and activate it later.

If you don’t select filter criteria, your governance profile applies rulesets to all of your APIs in Exchange.

Considerations

  • Start by saving your profiles as draft to test settings before revealing the targeted API’s conformance across Anypoint Platform.

  • Select fewer rulesets and add more filters to narrow the scope of a single profile.

  • Configure each profile to govern a related set of APIs for easier maintenance.

  • Start with governing just a few APIs until you are familiar with API Governance and establish governance processes in your organization.

To create a governance profile using the API Governance console:

  1. In API Governance, click New Profile.

  2. Follow the UI prompts to enter the following:

Select Rulesets

Select one or more rulesets to use to govern your APIs.

Use the search box and filters to find the rulesets to use. You can filter rulesets by the following:

  • Organization

  • Tag

  • Category

You can select the version of each ruleset to use or select the Latest option. The default is Latest.

  • If you select Latest, the profile automatically uses the latest version of that ruleset if any versions are published after the profile is saved. This ensures that the APIs selected in this profile are always validated against the latest version of rulesets without the need to manually update the profile.

  • If you select a specific version, the profile continues to use that version even if new versions of the rulesets are published after the profile is saved. This ensures that APIs selected in this profile that are conformant to a specific ruleset version are not inadvertently made nonconformant by a newly published version of the ruleset. You can update the profile and select a new version when you are ready to use the new ruleset version.

Define Filter Criteria

To apply selected rulesets to specific APIs, select filter criteria. The filter criteria applies to your organization’s APIs that are in Exchange and to new APIs as you add them to Exchange.

A preview of filtered APIs appears in the Define Filter Criteria page as you apply filters. The preview shows only a few APIs and is not searchable. After you save the profile, you can view and search the list of governed APIs for that profile.

General filters:

  • API Types

  • Tags

    The Tags section lists frequently used tags and the tags you add to the profile. See Select and Add Tags in Governance Profiles.

  • Categories

    Selections appear in the Categories section only if your APIs in Exchange have categories.

    If you filter by multiple tags and categories, your APIs must have all of the selected tags and categories to match the criteria. See Identifying APIs to Govern.

    If you filter by categories, you can see the number of categories for each API, which is denoted by Categories followed by a number in parenthesis. Hover over Categories to see more details.

API Instance filters:

  • Include only APIs with instances

    • Environment Type

    • Environment Name

If you select the API Instance filter Include only APIs with instances, only specifications that have an instance in API Manager are included. You can then optionally filter by environment type and environment name.

Set Notifications

Enable or disable automatic notifications for this profile. The default setting is enabled for active profiles. Notifications are automatically disabled for draft profiles. See Sending Conformance Notifications.

Specify General Information

Enter a profile name and description that helps others understand the kinds of governance rulesets included and the kinds of APIs validated in this profile.

Review

Review your profile and click Save as a draft or Save as active:

  • Save a profile as draft to test profile settings and review conformance information before showing the conformance information for its targeted APIs outside of the draft profile view.

  • Save a profile as active to show the conformance information outside of the draft profile view.

When you save a profile as either draft or active, its targeted APIs become governed.

Update a Governance Profile Using the API Governance Console

The API Governance console UI guides you through updating profiles.

To update governance profile information using the console:

  1. In the API Governance console Profiles tab, click Draft or Active.

  2. For the profile you want to update, click the more options menu icon (overflow menu icon) and then select Edit.

  3. Navigate through the UI using the Next and Previous buttons and update the profile information as needed. For details on the options, see Create a Governance Profile Using the API Governance Console.

  4. Review your changes and click Update Profile.

    After you apply your edits, the total APIs value refreshes to indicate how many APIs your governance profile includes based on your updated filter criteria.

Activate a Draft Governance Profile

To activate a draft profile:

  1. In the API Governance console Profiles tab, click Draft to show draft profiles.

  2. Click Activate for the profile to activate.

    After you activate a profile, its targeted APIs' conformance information appears outside of the draft profile view.

    If enabled, notifications are sent for failed validations.

Duplicate a Governance Profile

To duplicate a profile:

  1. In the API Governance console Profiles tab, click Draft or Active.

  2. Select a profile.

  3. Select Profile Settings > Duplicate.

    A copy of the profile opens.

  4. Follow the steps in Create a Governance Profile Using the API Governance Console.

Delete a Governance Profile Using the API Governance Console

To delete a governance profile:

  1. In the API Governance console Profiles tab, click the more options menu icon (overflow menu icon) for the profile to update and select Delete.

  2. Click Yes, Delete.

Create Governance Profiles Using the API Governance CLI

To use the CLI to create an API Governance profile, use the following command:

governance:profile:create

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

This command creates an active 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. See Get Exchange Asset Identifiers.

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

Besides the default flags, this command also accepts:

Flag Description

--criteria <filtertype:filtervalue>,…​

Enables you to apply filters to select the list of APIs to which the profile rulesets 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

  • 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.

    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,scope:rest-api,scope:async-api,env-type:production

--description <description>

The description flag 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-v4 governance:profile:create "OAS Best Practices" 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1 --criteria "tag:oas,category:API Type:Experience API,scope:rest-api" --description "Profile for OAS Best Practices"

anypoint-cli-v4 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,scope:rest-api" --description "Profile for OAS Best Practices"

anypoint-cli-v4 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,scope:rest-api" --description "Profile for REST API Best Practices" --notify-publisher  --notify-contact --notify-others a@a.a,b@b.com

anypoint-cli-v4 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,scope:rest-api" --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

List Governance Profile Information Using the API Governance CLI

To use the CLI to list governance profile information for all governance profiles, use the following command:

governance:profile:list

> governance:profile:list [flags]

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

Besides the default flags, this command also accepts:

Flag Description

--output <output-format>

Format for the command output. Supported values are table (default) and json.

Example command:

anypoint-cli-v4 governance:profile:list

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

List Specific Governance Profile Information Using the API Governance CLI

To use the CLI to list governance profile information for a specific governance profile ID, use the following command:

governance:profile:info

> governance:profile:info [flags] <profile-id>

This command lists all information for a governance profile ID.

Besides the default flags, this command also accepts:

Flag Description

--output <output-format>

Format for the command output. Supported values are table (default) and json.

Example command:

anypoint-cli-v4 governance:profile:info 19fb211b-8775-43cc-865a-46228921d6ed

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

Update a Governance Profile Using the API Governance CLI

To use the CLI to update a governance profile, use the following command:

governance:profile:update

> governance:profile:update [flags] <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 flags to update the notification configuration or turn off notifications. Any changes override existing notification configurations. If you do not use a notify flag, no changes are made to the notification configuration.

Besides the default flags, this command also accepts:

Flag Description

--profile-name <profile-name>

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

--ruleset-gavs <ruleset-gavs>

The ruleset-gavs flag is followed by 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.

--criteria <filtertype:filtervalue>,…​

Enables you to apply filters to select the list of APIs to which the profile rulesets 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

  • 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.

    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,scope:rest-api,scope:async-api,env-type:production

--description <description>

The description flag 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-v4 governance:profile:update 4eaf9176-3ef9-4021-a67c-6e4bc10d3763 --profile-name "MyOrg Best Practices"

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

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

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

anypoint-cli-v4 governance profile update 19fb211b-8775-43cc-865a-46228921d6ed --criteria `tag:best,category:API Type:Experience API,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

Get Exchange Asset Identifiers

To get the full asset identifier (group ID/asset ID/version) for Exchange assets:

  • If you are using Anypoint CLI, run the exchange:asset:list command.

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

Delete a Governance Profile Using the API Governance CLI

To use the CLI to delete a governance profile, use the following command:

governance:profile:delete

> governance:profile:delete [flags] <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 flags.

Example command:

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

Example output:

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

See Also