IBM® API Connect has added an optional add-on feature that allows organizations to validate APIs against governance policies and best practices. This ensures a designer creates APIs that conform to organization guidelines and quality. This feature is called API governance.
API governance:
-
uses rulesets and their associated rules to analyze Swagger, OpenAPI and AsyncAPI documents
-
based on open-source Spectral linter
-
includes OWASP, OAS and IBM provided sample rulesets
-
allows the creation of custom rulesets (and rules)
-
has global and provider organization ruleset definitions
Create a ruleset in cloud manager
Rulesets can be created in a number of ways, create from scratch, import or duplicate from an existing ruleset. It is possible to create rulesets that can span organizations or can be created for a single organization.
In the cloud manager, navigate to Resources and API governance:
The following panel will be presented:
Custom rulesets are added to Global rulesets, where a ruleset is manually created or imported directly. Once added, the ruleset can be published to all organizations or to specific organizations.
A ruleset has the following lifecycle:
| State |
Description |
|
Draft
|
Ruleset can be modified
|
|
Published
|
Ruleset cannot be modified as it is in use in organizations
|
|
Archived
|
Ruleset is removed from all organizations and removed from default view (filter can enable viewing of archived rulesets)
|
|
Deleted
|
Ruleset is permanently removed from API governance
|
A ruleset is comprised of general information, title, version, description and rules. Note version is a field that can’t be changed currently, a later update with enable full version support.
A rule has a title, description, message (for output), severity and the rule criteria. The rule criteria has a location called (Given) and a function (Then) element.
This sample has `given` set to `$` which indicates that the rule applies to all parts of API document and the `then` field narrows the criteria to specific element to search for using the `truthy` function. In this case, if the API document must contain a description in the info object and if the rule detects that the description is not present, the rule will fire.
Once created, the ruleset can be used to validate an API document:
Using the validate button, select the rule or rules to be used in the validation process, and upload an API document:
The sample API document does not have a description and following result is presented:
Subsequent rules can be added to the draft ruleset.
Once the changes to the ruleset are complete, it can be promoted to organizations using the Publish function. Note that once published, the ruleset cannot be changed.
It is possible to create rulesets in the manager user webpage, using the same method method as the cloud manager. Rulesets created in manager will only be available to this organization.
How to validate your existing APIs
Navigate to the API that you wish to validate and select “Validate” / “With rulesets”:
All rulesets shared with the organization are available for selection (including custom published from configuration manager):
Select the rulesets and the associated rules to be used in the validation and then “Validate”:
The results of the validation are presented:
The results can be filtered and searched to examine the findings and if required the results can be saved.
How to enable Governance
API governance needs API Connect version 10.0.6. To enable this feature, use the following guides as appropriate:
Enable on Kubernetes
Enable on VMware
More information
Full API governance information is available at the API Connect documentation page