Configuring API governance in the API Manager

How to add custom API governance rulesets to your API development process, to validate and enforce organizational governance policies and best practices in your provider organization.

• To create a new ruleset by using the API Manager or API Designer UI, complete the following steps.
  1. In the API Manager, click Resources.
  2. In the Resources navigation menu, select API governance.
  3. In the Provider organization rulesets section, click Add > Create from scratch.
     The Create provider organization ruleset wizard opens.
  4. Provide the following Ruleset info details.

     Property label	Required	Description	Data type
     Title	Yes	A short descriptive name for the ruleset. This name is displayed in the list of global rulesets.	String
     Name	Yes	An auto-generated, sluggified, string that is based on the title. It is not editable.	String
     Version	Yes	The version number defaults to 1.0.0, but can be edited. You can have rulesets with the same name, but with different version numbers. The version number must be in the format major.minor.patch.	String
     Description	No	An optional description of the ruleset.	String

  5. Click Next, and then add an initial rule to your ruleset.
  6. Provide the following Rule info details.

     Property label	Required	Description	Data type
     Title	Yes	A short descriptive name for the rule.	String
     Name	Yes	A short machine name for the rule. Can contain only alpha-numeric characters, underscores (_), and hyphens (-).	String
     Description	Yes	A description of the rule.	String
     Message	No	Provide a message to help users understand what the goal of the rule is. If no message is provided, the value of the Description property is used for the message output of the validation scan.	String
     Severity	Yes	Select a severity level from the following options: error warn info hint off error is selected by default.	String

  7. In the Given section, specify one or more values for the parts of the API document to target. To add more values, click Add. Values must be written in JSONPath.
  8. In the Then section, specify the function type and options that will be used to evaluate the target values in the API document. Write this section in YAML syntax.
     In the following example, for a Given value of $ (which means root level of the document), the Then section uses the Spectral core truthy function to check that the info.contact property value is not false, "", 0, null, or undefined.

     - field: info.contact
       function: truthy

     The Then section can also contain a list of functions to be applied to the Given part of the document. In the following example, for a Given value of $.info.version (which refers to the version property inside the info property at the root level of the document), the Then section uses both the truthy function, and the Spectral core pattern function that checks that the info.value matches the regex expression that is given by functionOptions.match.

     - function: truthy
     - function: pattern
       functionOptions:
         match: "^[0-9]+.[0-9]+.[0-9]+(-[a-z0-9+.-]+)?"

     For a complete list of the Spectral core functions that you can use in your custom rules, along with examples of these functions, see https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
  9. Click Create to create your draft ruleset.
     Your draft ruleset opens in design form view. Note that you can switch to the OpenAPI YAML source view by clicking the Source icon . To return to the design form view, click the Form icon .
  10. You now have the following options:
      • You can continue to edit your ruleset. For example, you can add more rules by clicking the Create rule icon alongside Rules in the navigation pane. Remember to click Save when you finish editing.
      • If you don't want to edit your ruleset further now, click API governance in the breadcrumb trail to return to the API governance overview page.
• To import an existing ruleset, complete the following steps. Remember that the rules in your imported ruleset can contain only built-in Spectral core functions, as defined in https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
  1. In the API Manager, click Resources.
  2. In the Resources navigation menu, select API governance.
  3. In the Provider organization rulesets section, click Add > Import.
     The Import ruleset wizard opens.
  4. Drag a file into the Upload file box, or click in the Upload file box to select a file to upload. The maximum file size is 100 kb, and the supported file types are YAML, YML, and JSON.
  5. Click Next.
  6. Edit the Ruleset info details as required, and click Import.
     Your draft ruleset opens in design form view. Note that you can switch to the OpenAPI YAML source view by clicking the Source icon . To return to the design form view, click the Form icon .
  7. You now have the following options:
     • You can continue to edit your ruleset. For example, you can add more rules by clicking the Create rule icon alongside Rules in the navigation pane. Remember to click Save when you finish editing.
     • If you don't want to edit your ruleset further now, click API governance in the breadcrumb trail to return to the API governance overview page.
• To create a ruleset by using the toolkit CLI, complete the following steps.
  1. Create a JSON file containing the new ruleset.

     The following example shows the contents of a Spectral Ruleset file for API Manager:

     {
       "name": "custom-ruleset",
       "title": "custom-ruleset",
       "description": "Info validation",
       "ruleset_type": "custom",
       "ruleset_version": "1.0.0",
       "rules": [
         {
           "name": "contact",
           "severity": "error",
           "formats": [
             "oas2",
             "oas3"
           ],
           "given": [
             "$"
           ],
           "description": "The info object must contain either a contact email or contact url",
           "then": [{
             "field": "info.contact",
             "function": "truthy"
           }]
         },
         {
           "name": "description",
           "severity": "error",
           "formats": [
             "oas2",
             "oas3"
           ],
           "given": [
             "$"
           ],
           "description": "The info object must contain a description",
           "then": [{
             "field": "info.description",
             "function": "truthy"
           }]
         }]
     }

  2. Log in to the toolkit as an the owner or an admin of the provider organization that owns the new ruleset.
     For example:

     apic login --server mgmt_endpoint_url --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 mgmt_endpoint_url --fields title,realm

     For example,

     apic identity-providers:list --scope provider --server myserver.com --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.

  3. Run the rulesets:create toolkit command in governance mode:

     apic -m governance rulesets:create --org <target_org> --server <server_url> RULESET_FILE

     where:

     • <target_org> is the name of the organization that owns the new ruleset.
     • <server_url> is the management server URL that you use for logging in to the toolkit.
     • RULESET_FILE is the path and filename of the JSON file that contains the ruleset.