Validating an API or product document by using the toolkit CLI

How to use the API Connect toolkit CLI to run governance validation scans on your API or product documents.

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.

The following validation scan methods are available by using the toolkit CLI:

Validate a single API or product document that is stored locally

To run a validation scan on a single API or product document against one or more rulesets, complete the following steps. The document must be stored locally.
  1. Log in to the toolkit as the owner or an admin of your provider organization.
    For example: 
    apic login --server platform_api_host_name --username user_id --password password --realm provider/identity_provider
    You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
    apic identity-providers:list --scope provider --server platform_api_endpoint_url --fields title,realm
    For example,
    apic identity-providers:list --scope provider --server platform_api_endpoint_url --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
    The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.

    For full details of the apic login command, see Logging in to a management server.

  2. Run the compliance:validate toolkit command in governance mode.
    apic --mode governance compliance:validate --org <target_org> --server <platform_api_host_name> --rulesets <ruleset_name_1>,<ruleset_name_2> API_OR_PRODUCT_FILE
    where:
    • <target_org> is the name of the provider organization that owns the APIs to be validated.
    • <platform_api_host_name> is the hostname portion URL of server that hosts the API Manager (the "management server").
      Tip: To determine the hostname, you can open the API Manager in a browser and copy the hostname from the URL in the address bar (beginning after https:// and ending before /manager).
    • <ruleset_name_1>,<ruleset_name_2> is a comma-delimited list specifying the names of the rulesets to be applied to the API or product. (Specify each ruleset name; do not use the ruleset IDs.)
    • API_OR_PRODUCT_FILE is the path and filename of the document to be validated.

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 <platform_api_host_name> COMPLIANCE_REQUEST_FILE
    where:
    • <target_org> is the name of the provider organization that owns catalog containing the APIs to be validated.
    • <platform_api_host_name> is the hostname portion URL of server that hosts the API Manager (the "management server").
      Tip: To determine the hostname, you can open the API Manager in a browser and copy the hostname from the URL in the address bar (beginning after https:// and ending before /manager).
    • 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).