salesforce Dreamforce On-Demand
Contact Us 1-800-596-4880
  1. Homepage
  2. API Governance
  3. Finding and Fixing Conformance Issues

  4. Fixing Specifications in Design Center

Fixing Specifications in Design Center

You can check for API specification conformance using one of the rulesets provided by MuleSoft or a custom ruleset. Some of the MuleSoft-provided rulesets that validate specification information are:

  • Anypoint Best Practices

  • Authentication Security Best Practices

  • OpenAPI Best Practices

  • AsyncAPI Best Practices

  • Required Examples

You can check specification conformance in API Governance and Design Center and by using Anypoint CLI.

Validate API Specifications in Governance Profiles

To validate APIs against governance rulesets in API Governance profiles, see Applying Rulesets to Identified APIs.

Validate API Specifications Using Anypoint CLI

To validate against rulesets using CLI without using a governance profile, use the governance:api:validate command.

governance:api:validate

> governance:api:validate <api-specification> [flags]

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

This command has multi-option flags. When using multi-option flags in a command, either put the parameter before the flags or use "-- " (two dashes followed by a space) before the parameter.

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

  • An API project ZIP file

  • An API project folder

  • An asset identifier for an API project, if the --remote flag 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 the exchange.json file is included in the folder or ZIP file that you specify in api-specification. If the exchange.json file is present, the command downloads all of the ruleset dependencies and validates against those rulesets. The ruleset dependencies are present in the exchange.json file only if dependencies are defined for that API project in API Designer. See Add Rulesets to Your Project.

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

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

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 might be validated multiple times.

Besides the default flags, this command also accepts:

Flag Description

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

Local ruleset definitions. The rulesets flag is followed by a list of ruleset YAML files separated by spaces.

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

Remote ruleset definitions. The remote-rulesets flag is followed by a list of ruleset asset identifiers separated by spaces. 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.

--remote

Flag to indicate that the validation should be done against a published API. The value passed in api-specification 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.

Example commands:

anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip

anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml

anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip --rulesets /MyRulesets/ruleset1.yaml /MyRulesets/ruleset2.yaml

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

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

Example output:

For a specification that is conformant to the ruleset:

 Spec conforms with Ruleset

For a specification 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 specification 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

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.

View Specification Conformance Issue Details in the Governance Report

To view specification conformance issues in the governance validation report:

  1. In the API Governance console, select the Governed APIs tab.

  2. If the API has a Not Conformant badge, click View Report for information about the conformance issue.

    1. View all issues:

      Click View Details for a ruleset the API is nonconformant to.

    2. View issues for the specification only:

      1. Select Specification in the Conformance Breakdown section of the report.

      2. Click View Details for a ruleset the specification is nonconformant to.

Validate API Specifications in Design Center

If your API is governed using API Governance, you can use the detailed governance report in API Governance to find any centralized governance conformance issues. If your API is not governed using API Governance or if you want to see conformance issues directly in API Designer, you can validate your API in API Designer.

To validate APIs against governance rulesets in Design Center, add the rulesets as dependencies to API specifications in the Design Center API Designer text editor. After you add the rulesets, expand the Project Errors section to view conformance messages.

Screenshot of rulesets applied as dependencies in API Designer
1 Add rulesets to your API project as dependencies.
2 Expand the Project Errors section of the text editor to view nonconformance messages.
3 Click Validate for governance to initiate validation if Governance auto-validation is disabled. See Improving Ruleset Validation.
4 View conformance issues and filter by level of severity.

Add Rulesets to Your Project

In API Designer, you can add governance rulesets to your API projects as Exchange dependencies.

If your API has been identified as governed through centralized API governance, a dot or warning icon appears on the Exchange dependencies icon to indicate you need to take action on the dependencies for this project. Click the Exchange dependencies icon to view and follow the interactive instructions to add rulesets as dependencies to your project.

See Adding Dependencies to an API-Specification Project.

Fix API Specification Issues in Design Center

After your specifications are identified as nonconformant through validation against rulesets, either through API Governance profiles or through ruleset dependencies in Design Center, you can fix them in API Designer.

See Create an API Specification with the Text Editor.

See Also