Contact Us 1-800-596-4880
  1. Homepage
  2. API Governance
  3. Creating Custom Governance Rulesets

  4. Validating and Publishing Custom Rulesets

Validating and Publishing Custom Rulesets

After you create a custom ruleset:

  1. Validate the ruleset.

  2. Generate the documentation for the ruleset.

  3. Publish your custom ruleset to Exchange as a new asset.

For an example sequence of commands to validate and publish your rulesets, see Example Command Sequence to Validate and Publish.

As with custom code and configurations, rulesets are not considered supported MuleSoft products. For help with issues with custom rulesets, post an issue in the AMF Custom Validator Github repository.

Validate the Ruleset

To validate your governance ruleset as you create it and before you publish it, use the following command:

governance:ruleset:validate

> governance:ruleset:validate [flags] <governance-ruleset>

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 the default flags.

Example commands:

anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myruleset.yaml

anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myruleset.zip

anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myrulesetfolder

Example output for a valid ruleset:

Ruleset User/myuser/myrulesetfolder/myruleset.yaml
Ruleset conforms with Dialect

Example output for a nonvalid ruleset:

Ruleset does not conform with Dialect
ModelId: file:///Users/myuser/myrulesetfolder/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/myuser/myrulesetfolder/prof-1-bad.yaml#/encodes
  Property: http://schema.org/name
  Range: [(3,0)-(11,19)]
  Location: file:///Users/myuser/myrulesetfolder/prof-1-bad.yaml

Generate the Ruleset Documentation

Use the following command to generate a documentation ZIP file for a ruleset YAML file. Upload the resulting documentation ZIP file along with its associated ruleset file using the anypoint-cli-v4 exchange asset upload command.

governance:document

> governance:document [flags] <ruleset> <doc-file>

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 the default flags.

Example command:

anypoint-cli-v4 governance:document /myrulesetfolder/mynewruleset.yaml /myrulesetfolder/ruleset.doc.zip

Example output:

validation name [ 'security-fields-operation-empty' ]
validation name [ 'access-tokens-oauth2-cleartext' ]
validation name [ 'insecure-oauth2-grants' ]
validation name [ 'api-keys-in-cookie' ]
validation name [ 'api-keys-in-query' ]
validation name [ 'api-keys-in-header' ]
validation name [ 'api-negotiates-authentication' ]
validation name [ 'insecure-basic-auth' ]
validation name [ 'bearer-token-cleartext' ]
validation name [ 'http-token-cleartext' ]
validation name [ 'oauth1-deprecated' ]
validation name [ 'oauth2-redirections-non-encrypted' ]
validation name [ 'unknown-security-scheme' ]
validation name [ 'valid-server-urltemplate' ]
validation name [ 'valid-oauth2-redirection-urls' ]
Saving to myRulesetFolder/ruleset.doc.zip

Publish the Custom Ruleset

You can publish (upload) a ruleset and its documentation to Exchange using the following Anypoint CLI command.

exchange:asset:upload

> exchange:asset:upload [flags] <assetIdentifier>

Uploads a rest-api, soap-api, http-api, raml-fragment, custom, app, template, example, policy, extension, external-library, connector asset, or ruleset using the ID passed in <assetIdentifier>

Argument assetIdentifier should be formatted as follows: ([group_id]/)<asset_id>/<version>
If group_id is not specified, it defaults to the currently selected Organization ID

In addition to the default flags, this command accepts the following flags:

Flag Description Example

--categories

Categories (value should be a string in JSON format)

--categories '{"Department": "IT"}'

--dependencies

Asset dependencies (comma-separated)

--dependencies groupID:assetID:version,groupID2:assetID:version

--description

Asset description

--description "RAML"

--files

Asset file, identified as classifier.packaging or packaging and its file path
To send multiple files, you can use the same flag multiple times.
An exception to this is when you upload ruleset documentation with a ruleset. Both sets of classifiers and packaging options must be entered in a single --files flag

To upload a POM file and a RAML specification:

--files'{"pom.xml": "directory/pom-file.xml"}' --files='{"raml.raml": "./my-api.raml"}'

To upload a ruleset and its documentation:

anypoint-cli-v4 exchange asset upload my-auth-best-practices/1.0.0 --name "My Best Practices Ruleset" --description "This ruleset enforces my best practices for APIs." --files='{"ruleset.yaml":"/myRulesetFolder/mynewruleset.yaml","docs.zip":"/myRulesetFolder/ruleset.doc.zip"}'

--fields

Fields (value should be a string in JSON format)

--fields '{"releaseDate": "2020-01-01T20:00:00.000Z"}'

--keywords

Keywords (comma-separated)

--keywords raml,rest-api,someKeyword

--name

Asset name (required if no pom file is specified)

--name "Raml Asset"

--properties

Asset properties
The file of the specified "mainFile" property must be in the uploaded zip file on the root path. The file cannot be in a subfolder.

--properties='{"apiVersion":"v1", "mainFile":"api.raml", "contactName":"contact", "contactEmail":"example@mulesoft.com"}'

--status

Asset status
Supported Values:

  • development

  • published (default)

--status development

--tags

Tags (comma-separated)

-- tags api,tag1,tag2

--type

Asset type

Required if no file is specified.

Supported Values:

  • rest-api

  • soap-api

  • http-api

  • raml-fragment

  • custom

  • connector

  • template

  • example

  • policy

  • app

  • extension

  • external-library

  • ruleset

If it is uploaded, the type is inferred from the classifier of the file

Depending on the type of asset, some possible classifier values are:

  • REST API

    • oas (with zip, yaml, or json as packaging)

    • raml (with zip or raml as packaging)

  • RAML Fragment

    • raml-fragment (with zip or raml as packaging)

  • SOAP API

    • wsdl (with zip, wsld, or xml as packaging)

  • Custom

    • custom

    • docs (with doc.zip as packaging)

  • Application

    • mule-application (with jar as packaging)

  • Policy

    • mule-policy (with jar as packaging) + policy-definition (with yaml as packaging)

  • Example

    • mule-application-example (with jar as packaging)

  • Template

    • mule-application-template (with jar as packaging)

  • Extension

    • mule-plugin (with jar as packaging)

  • Connector

    • studio-plugin (with zip as packaging) + file with no classifier and packaging jar

  • External Library

    • external-library (with jar as packaging)

  • Ruleset

    • ruleset (with zip or yaml as packaging)

--type rest-api

Example Command Sequence to Validate and Publish

Use the following example sequence to get started validating your ruleset, generating its documentation, and uploading both to Exchange. Replace the details, such as the folder name, ruleset file name, and ruleset documentation ZIP file name, with your own.

anypoint-cli-v4 governance:ruleset:validate /myRulesetFolder/mynewruleset.yaml (1)

anypoint-cli-v4 governance:document /myRulesetFolder/mynewruleset.yaml /myRulesetFolder/ruleset.doc.zip (2)

anypoint-cli-v4 exchange asset upload my-auth-best-practices/1.0.0 --name "My Best Practices Ruleset" --description "This ruleset enforces my best practices for APIs." --files='{"ruleset.yaml":"/myRulesetFolder/mynewruleset.yaml", "docs.zip": "/myRulesetFolder/ruleset.doc.zip"}' (3)
1 Validates the ruleset locally. The ruleset file is mynewruleset.yaml in the /myRulesetFolder/ folder.
2 Generates the documentation ZIP file, ruleset.doc.zip, for the ruleset myruleset.yaml. Both files are in the /myRulesetFolder/ folder.
3 Uploads the ruleset, mynewruleset.yaml, and its documentation, ruleset.doc.zip. Both files are in the /myRulesetFolder/ folder.

See Also