-
The specification has this markup:
#%RAML 1.0 title: my-des-with-governance protocols: - HTTP
-
The design project for the specification applies these rulesets:
-
HTTPS Enforcement
-
Anypoint Best Practices
-
Validating API Specifications Against Governance Rulesets
Test your API specifications in Anypoint Code Builder design projects against rules in governance rulesets, and fix conformance issues that result.
For information about rulesets and governance, see Anypoint API Governance Concepts.
Before You Begin
You must have an API design project with a supported specification in Anypoint Code Builder. See Creating and Importing API Specifications.
Ensure that your API specification is supported. See API governance Compatibility.
Workflows and tasks
A typical workflow consists of one or more of the following tasks:
-
Add one or more rulesets to an API design project:
-
Run rules in the rulesets to determine if your API specification conforms with the rules:
-
Fix any conformance issues in the specification:
Add Rulesets to a Project
Add governance rulesets as dependencies to your API design project in Anypoint Code Builder.
Rulesets are hosted on Exchange. MuleSoft provides a number of public rulesets that you can find from Anypoint Code Builder or review directly on Exchange. For example, the ruleset Anypoint Best Practices provides documentation and examples. Your team can also create and publish rulesets for your organization to Exchange (see Creating Custom Governance Rulesets).
-
Open your API design project in Anypoint Code Builder.
-
From the Explorer, expand the Governance Rulesets panel in your project.
If the panel is not in the Explorer, activate the panel from the Views and More Actions… (…) menu in the Explorer.
-
Add a ruleset:
-
If the panel does not contain any rulesets, click Add Rulesets. For example:
-
If the panel contains rulesets, you can hover over the panel and click
(Add Governance Rulesets) to add another ruleset. For example:
-
-
If prompted, sign in to Anypoint Platform.
-
Search for the ruleset, and click Add Rulesets. For example:
You can also narrow your search to specific organizations from the Any organization menu, and you can select a different version of a ruleset if more than one version is available.
-
Proceed to Run Rules Against Your API Specification.
Run Rules Against Your API Specification
Determine whether your API specification conforms with rules in governance rulesets.
-
Open your API design project in Anypoint Code Builder.
-
From the Explorer, expand the Governance Rulesets panel to check for rulesets in your project.
-
If any rulesets are present and you don’t intend to add more, proceed to the next step.
-
If no rulesets are present or if you intend to add more rulesets, go to Add Rulesets to a Project.
-
-
Run rules from the Governance Rulesets panel.
You can run rulesets at multiple levels:
-
All rules in all rulesets
-
All rules in a single ruleset
-
A single rule in a ruleset
You can monitor the rules as they run. For example:
-
-
If any rules return an error (
) or a warning (
), proceed to Fix Conformance Issues.
For example, this ruleset returns a warning on some rules:
Execution times displayed for a ruleset (such as 19.25s) represent the sum of time it takes to run each rule. Due to parallel execution of rules on machines with multiple cores, the execution time displayed for a ruleset is likely to be greater than the actual time to complete the execution.
The Governance Results panel also identifies any warnings or errors. For example:
Fix Conformance Issues
To address rules that return errors or warnings, fix the specification to comply with the rules. Then re-run the rules to ensure that the fix is effective.
Example
To illustrate the process for addressing issues, the example in this procedure starts with a partial RAML specification and some rulesets:
Full Example
Fix Conformance Issues
To fix errors () and warnings (
):
-
Run the rulesets in your project.
For guidances, see Run Rules Against Your API Specification.
-
Review any resulting errors and warnings in the Governance Results panel. For example:
Governance Results lists the corresponding issues. For example:
-
Error: [HTTPS Enforcement] Only use https protocol scheme.
-
Warning: [Anypoint Best Practices] Provide the documentation for the API.
-
Warning: [Anypoint Best Practices] Provide the description for the API.
-
-
Address errors in the specification.
For instance, fix the HTTPS Enforcement error in the specification example by changing
HTTP
toHTTPS
:#%RAML 1.0 title: my-des-with-governance protocols: - HTTPS
-
Re-run the failing rule to ensure that the error is fixed.
For instance, after fixing the
protocols
error in the specification example, run use-https-for-scheme-protocol from the Governance Rulesets panel. For example:Notice that the error no longer appears in Governance Rulesets. For example:
In addition, the Governance Results panel no longer lists the issue.
-
Address warnings, as needed.
For instance:
-
Address the warning
Provide the description for the API
by adding adescription
to the specification example. For example:#%RAML 1.0 title: my-des-with-governance description: my description protocols: - HTTPS
The description is between
title
andprotocols
. -
Re-run the rule api-must-have-description, and notice that the specification now conforms to the rule.
The ruleset continues to identify a warning because a different rule in the ruleset has a warning.
-
-
Address any remaining issues that you intend to fix.
For instance, for the warning
Provide the documentation for the API
in the example, add and savedocumentation
markup to the specification:#%RAML 1.0 title: my-des-with-governance description: my description documentation: - title: My Title content: | Welcome to my API documentation. - title: Legal content: | This is my legal documentation. protocols: - HTTPS
-
Re-run the corresponding rule from the Governance Rulesets panel.
For example, re-run api-must-have-documentation, and notice that the specification now conforms to the rule.
The specification has no more errors or warnings. For example:
Remove a Ruleset from a Project
-
In the Governance Ruleset panel, hover over a ruleset to display the More actions (…) menu.
-
In the More actions menu, click Remove Ruleset….
You can also use the command MuleSoft: Remove Governance Ruleset… from the command palette for this purpose.
Open a Ruleset YAML File
To examine the configuration of a ruleset’s YAML file:
-
In the Governance Ruleset panel, hover over a ruleset to display its More actions (…) menu.
-
Click Show in Files to open the YAML file in a ruleset.yaml tab in the IDE.
The following example shows version 1.6.1 of the HTTPS Enforcement YAML file:
#%Validation Profile 1.0
profile: HTTPS enforcement
description: This ruleset helps ensure the use of HTTPS across URLs in API
definitions, both in the base server URL and in any callbacks optionally
defined.
violation:
- use-https-for-callbacks
- use-https-for-scheme-protocol
- use-https-for-urls
tags:
- security
validations:
use-https-for-callbacks:
message: "{{apiContract.expression}} must use https as it is a callback url"
targetClass: apiContract.Callback
propertyConstraints:
apiContract.expression:
pattern: ^https://
examples:
valid: |
openapi: "3.0.0"
info:
title: example API
version: "1.0.0"
paths:
/subscribe:
post:
responses:
'201':
description: Webhook created
callbacks:
myEvent:
'https://{$request.body#/callbackUrl}'
invalid: |
openapi: "3.0.0"
info:
title: example API
version: "1.0.0"
paths:
/subscribe:
post:
responses:
'201':
description: Webhook created
callbacks:
myEvent:
'http://{$request.body#/callbackUrl}'
use-https-for-scheme-protocol:
message: Only use https protocol scheme
targetClass: apiContract.WebAPI
not:
propertyConstraints:
apiContract.scheme:
containsSome:
- HTTP
- http
examples:
valid: |
#%RAML 1.0
protocols:
- HTTPS
invalid: |
#%RAML 1.0
protocols:
- HTTP
use-https-for-urls:
message: "{{core.urlTemplate}} should use https"
targetClass: apiContract.Server
propertyConstraints:
core.urlTemplate:
pattern: ^https://
examples:
valid: |
openapi: "3.0.0"
servers:
- url: "https://mySecureEndpoint"
description: "My endpoint that uses HTTPS"
invalid: |
openapi: "3.0.0"
servers:
- url: "http://myNotSoSecureEndpoint"
description: "My endpoint that uses HTTP"