Validating an API or product document by using the governance service

How to use governance rulesets to validate and enforce organizational governance policies and best practices. You can run validation scans on API and product documents from the API Manager UI, the API Designer UI, or the toolkit CLI.

Before you begin

Before you can run validation scans you must have governance enabled on your management subsystem by your system administrator. See Enabling governance on Kubernetes, and Enabling governance on VMware for more information. If governance is enabled in your deployment, the Governance icon The governance icon is the outline of a shield in white, on a black background. is displayed in the side menu bar. If you are only a catalog or space member of a provider organization, a Governance tab is visible in the catalog menu.

The governance service is available to all user roles.

Tip: Before using the governance service to validate any API documents, you should first run Validate > With specifications to validate the OpenAPI YAML source. For more information, see Validating the OpenAPI YAML source.

About this task

The governance service in IBM® API Connect can be used to validate and enforce organizational governance policies and best practices to your API and product development process. The service contains the following types of rulesets:
API
Rulesets to validate your API documents.
  • Provider organization rulesets - these are custom rulesets that contain the rules that are created in, and are specific to, your provider organization for validating APIs.
  • Global rulesets - these are pre-configured IBM and Spectral rulesets that contain the rules that are shared with your provider organization for validating APIs, and cannot be edited. Note that the Spectral ruleset names are prefixed by spectral-, and that their version matches the version of that ruleset that's available in Spectral.
Product
Rulesets to validate your product documents. Note that the validation scan of products looks only at the product yaml; it does not include the scanning of any API documents that the product refers to.
  • Provider organization rulesets - these are custom rulesets that contain the rules that are created in, and are specific to, your provider organization for validating products.
  • Global rulesets - these are pre-configured custom rulesets that contain the rules that are shared with your provider organization for validating products, and cannot be edited.

You can create your own provider organization rulesets to validate your Swagger, OpenAPI, AsyncAPI, and product documents against, or use the global rulesets that are provided for your organization. For more information about configuring rulesets, see Configuring governance in the API Manager.

Governance in API Connect is based on the open source Spectral linter; for more information about Spectral, see https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview.

You can complete the instructions that are in this task by using the API Manager UI, or by using API Designer when the UI is online, and is connected to a cloud instance that has the governance microservice enabled on it. You can also use the toolkit CLI; for details see Validating an API or product document by using the toolkit CLI.

The following validation scan methods are available:

Procedure

  • To validate an API document from within the API, complete the following steps.
    1. Open the required API for validating, as described in Editing an OpenAPI 2.0 API definition or Editing an OpenAPI 3.0 API definition.
    2. Click Validate > With rulesets from the menu bar in the header.
      Screen capture of the header menu bar showing the Validate button, and the Save button.
    3. Select the rulesets that you want to validate your API document against, and click Next.
      If there are matching tags in the APIs and in the rulesets, the validation process preselects which rulesets to use for the scan. However, you can override this preselection with rulesets of your choice. For information about how to add tags, see Configuring governance in the API Manager, and Adding tags to an API.
    4. Select the rules from within the rulesets that you want to use for the validation. By default, all of the rules are selected.
    5. Click Validate.
      If any validation errors are found, a scorecard is displayed showing the results of the validation. The API can then be updated to resolve the validation errors, and validated again. If no errors are found, a success message is displayed.
    6. Optional: You can click Download to download the results of the validation into a .csv file.
    7. Optional: You can click Back to change the rulesets and rules, and then run the validation again.
    8. Click Done when finished.
      The API Design page is displayed.
      If validation errors were found during the scan, the ruleset status icon in the header menu bar displays the number of errors found, for example:
      Screen capture of the header menu bar showing the ruleset status icon of a black outline of a shield on a white background, with the number of errors found in the validation scan shown as a white number 38 inside a red circle next to the shield.
      You can click on the ruleset status icon to see a detailed list of the errors, and their location in the YAML. You can also then click on an individual error to navigate directly to the relevant section in the API.
  • To validate a product document from within the product, complete the following steps.
    1. Open the required product for validating, by clicking on the title of the product in the Products tab of the Develop page.
    2. Click Validate with rulesets from the menu bar in the header.
      Screen capture of the header menu bar showing the Validate button, and the Save button.
    3. Select the rulesets that you want to validate your product document against, and click Next.
    4. Select the rules from within the rulesets that you want to use for the validation. By default, all of the rules are selected.
    5. Click Validate.
      If any validation errors are found, a scorecard is displayed showing the results of the validation. The product can then be updated to resolve the validation errors, and validated again. If no errors are found, a success message is displayed.
    6. Optional: You can click Download to download the results of the validation into a .csv file.
    7. Optional: You can click Back to change the rulesets and rules, and then run the validation again.
    8. Click Done when finished.
      The product Design page is displayed.
  • To validate one or more draft API or product documents from within the Governance section, complete the following steps.
    1. In the side menu bar, click The governance icon is the outline of a shield in white, on a black background. Governance.
      The Governance page is displayed.
    2. Click the Rulesets tab.
    3. If you want to validate one ore more API documents, click the API tab. If you want to validate one or more product documents, click the Product tab.
    4. Click Validate.
    5. Select the rulesets that you want to validate against, and click Next.
      If there are matching tags in the APIs and in the rulesets, the validation process preselects which rulesets to use for the scan. However, you can override this preselection with rulesets of your choice. For information about how to add tags, see Configuring governance in the API Manager, and Adding tags to an API.
    6. Select the rules from within the rulesets that you want to use for the validation, and click Next.
    7. Select the APIs or products that you want to validate, and click Validate.
      If any validation errors are found, a scorecard is displayed showing the results of the validation. If no errors are found, a success message is displayed.
    8. Optional: You can click Download to download the results of the validation into a .csv file.
    9. Optional: You can click Back to change the rulesets, rules, and APIs, and then run the validation again.
    10. Click Done when finished.
  • To validate one or more published API or product documents from within a catalog or space, complete the following steps.
    1. Select the catalog or space that you want to run the validation in, and then select Governance from the menu bar.
    2. Select Rulesets.
    3. If you want to validate one ore more API documents, click the API tab. If you want to validate one or more product documents, click the Product tab.
    4. Click Validate.
    5. Select the rulesets that you want to validate against, and click Next.
      If there are matching tags in the APIs and in the rulesets, the validation process preselects which rulesets to use for the scan. However, you can override this preselection with rulesets of your choice. For information about how to add tags, see Configuring governance in the API Manager, and Adding tags to an API.
    6. Select the rules from within the rulesets that you want to use for the validation, and click Next.
    7. Select the APIs or products that you want to validate, and click Validate.
      If any validation errors are found, a scorecard is displayed showing the results of the validation. If no errors are found, a success message is displayed.
    8. Optional: You can click Download to download the results of the validation into a .csv file.
    9. Optional: You can click Back to change the rulesets, rules, and APIs, and then run the validation again.
    10. Click Done when finished.

Results

Your API or product document is validated against one or more rulesets.

What to do next

You can use the results of the validation to help you improve your API or product document. You can also use the results to help you edit the rulesets, and create new rulesets; see Configuring governance in the API Manager for more information.

You can also run validation scans on a catalog or space, to check one or more of the API documents that it contains. For more information, see Scanning your catalogs and spaces.