Validating an API or product document by using the toolkit CLI

About

The governance service in IBM® API Connect can be used to validate and enforce organizational governance policies and best practices to your API development process. The following information provides details of the toolkit CLI commands for running and managing validation scans on your API or product documents. You can also validate an API or product document by using the API Manager and the API Designer UIs. For more information about validation scanning, see Validating an API or product document by using the governance service.

Validate a single API or product document that is stored locally

Validate one or more APIs or products that are stored on the management server

This operation runs a validation scan on all of the draft APIs, or all of the products, that are listed in the COMPLIANCE_REQUEST_FILE. You can scan only APIs, or only products, at any one time. The APIs must be stored as draft APIs in your provider organization.

1. Create a JSON COMPLIANCE_REQUEST_FILE that specifies the rulesets to use during validation, and the location of either the draft APIs or the products that you want to scan. The file can contain URLs only for APIs, or only for products; you cannot list both API and product URLs in the same file.
   The following example shows a configuration file that specifies two draft APIs, and two rulesets. In the spectral-oas ruleset, the info-contact rule is disabled and will be ignored during validation.

   {
     "apiUrls" : ["https://example.com/api/orgs/768a5f80-177c-4100-b2b6-57ce6c4bf761/drafts/draft-apis/a08898fe-b422-41d3-b058-c3280d632e93","https://example.com/api/orgs/768a5f80-177c-4100-b2b6-57ce6c4bf761/drafts/draft-apis/26692eab-f43b-4af3-985c-2deaa401eb7f"],
     "config" : {
       "rulesets": [
         {
           "rulesetName": "spectral-oas",
           "disabled": ["info-contact"]
         },
         {
           "rulesetName": "spectral-owasp",
           "disabled": []
         }
         ]
    }
   }

   The following example shows a configuration file that specifies one product document.

   {
     "productUrls" : ["https://example.com/api/orgs/768a5f80-177c-4100-b2b6-57ce6c4bf761/drafts/draft-product/a07968fe-b422-41d3-b058-c3280d632e93"],
     "config" : {
       "rulesets": [
         {
           "rulesetName": "product-info",
           "disabled": ["subscribe"]
         },
         {
           "rulesetName": "product-rate",
           "disabled": []
         }
         ]
    }
   }

   Where:

   • apiUrls is a comma-delimited list of API URLs. Each URL specifies the location of the draft APIs in a particular provider organization.
   • productUrls is a comma-delimited list of product URLs. Each URL specifies the location of the product document in a particular provider organization.
   • rulesetName is a list of rulesets to be applied to the APIs or products during validation.

     For each ruleset in the list, you can optionally add the disabled property with a comma-delimited list of rules to ignore during validation.

2. Log in to the toolkit as the owner or an admin of your provider organization. See Step 1 for details.
3. Run the compliance:validate_all toolkit command in governance mode.

   apic --mode governance compliance:validate_all --org <target_org> --server <server_url> COMPLIANCE_REQUEST_FILE

   where:

   • <target_org> is the name of the provider organization that owns catalog containing the APIs to be validated.
   • <server_url> is the management server URL that you use for logging in to the toolkit.
   • COMPLIANCE_REQUEST_FILE is the path and filename of the configuration file that lists the API or product documents, and the rulesets to be used during the validation (for example, validate-apis.json).