Configuring governance in the API Manager

How to add custom 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 API or product ruleset by using the API Manager or API Designer UI, complete the following steps.
  1. In the side menu bar, click Governance.
     The Governance page is displayed.
  2. If you want to create an API ruleset, click the API tab. If you want to create a product ruleset, click the Product tab.
     The manage rulesets page is displayed.
  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. Optional: For API rulesets, you can add one or more tags to your ruleset by clicking Add, and completing the tag Name and Description.
     Adding matching tags to your rulesets and APIs, means that validation scans can preselect 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 to APIs, see Adding tags to an API.
  6. Click Next, and then add an initial rule to your ruleset.
  7. Provide the following Rule info details.

     Property label	Required	Description	Data type
     Title	Yes	A short descriptive name for the rule.	String
     Name	Yes	An auto-generated, sluggified, string that is based on the title. It is not editable.	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

  8. In the Given section, specify one or more values for the parts of the API or product document to target. To add more values, click Add. Values must be written in JSONPath.
  9. In the Then section, specify the function type and options that will be used to evaluate the target values in the API or product document. Write this section in YAML syntax.
     In the following API rule 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 API rule 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 API rules, along with examples of these functions, see https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
  10. 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 .
  11. 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 Governance in the breadcrumb trail to return to the API governance overview page.
• To import an existing API or product 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 side menu bar, click Governance.
     The Governance page is displayed.
  2. If you want to create an API ruleset, click the API tab. If you want to create a product ruleset, click the Product tab.
     The manage rulesets page is displayed.
  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 Governance in the breadcrumb trail to return to the API governance overview page.
• To create an API or product ruleset by using the toolkit CLI, complete the following steps.
  1. Create a JSON file that contains the new ruleset.

     The following JSON shows the contents of an example API document Spectral ruleset file:

     {
         "name": "short-draft-ootb",
         "title": "short-draft-ootb",
         "description": "short ruleset",
         "ruleset_type": "custom",
         "tags": [
           {
             "name": "general",
             "description": "general work"
           }
         ]
         "rules": [
           {
             "name": "sec-array-boundaries-2",
             "description": "Array size should be limited to mitigate resource exhaustion attacks.\nThis can be done using `maxItems` and `minItems`, like in the example\nbelow.\n\n```\nLimited:\n  type: array\n  maxItems: 10\n  items:\n    type: string\n    format: date\n```\n\nYou should ensure that the schema referenced in  `items` is constrained too.\n\nIf you delegate input validation to a library or framework,\nbe sure to test it thoroughly and ensure that it verifies `maxItems`.",
             "message": "Schema of type array must specify maxItems and minItems. {{path}} {{error}}",
             "formats": [
               "oas3"
             ],
             "severity": "warn",
             "recommended": true,
             "given": [
               "$..[?(@.type==\"array\")]"
             ],
             "then": [
               {
                 "field": "maxItems",
                 "function": "defined"
               }
             ]
           }
         ]
       }

     The following JSON shows the contents of an example product document ruleset file:

     {
       "type": "ruleset",
       "ruleset_type": "custom",
       "api_version": "2.0.0",
       "id": "dbb5f400-e707-412e-b081-ac36f5afbbb9",
       "name": "test-product",
       "title": "Test Product",
       "description": "",
       "ruleset_version": "1.0.0",
       "ruleset_state": "draft",
       "ruleset_format_type": "2",
       "rule_urls": [
         "https://my.manager.com/governance/orgs/myorg/rulesets/1.0.0-test-product/rules/ca6ef7d9-a503-498e-8f53-4e3aa35d086b"
       ],
       "created_at": "2024-05-22T17:19:02.820Z",
       "updated_at": "2024-05-22T17:24:59.000Z",
       "url": "https://my.manager.com/governance/orgs/myorg/rulesets/dbb5f400-e707-412e-b081-ac36f5afbbb9",
       "rules": [
         {
           "api_version": "2.0.0",
           "id": "ca6ef7d9-a503-498e-8f53-4e3aa35d086b",
           "name": "subscribe",
           "version": "1.0.0",
           "title": "subscribe",
           "description": "subscribe enabled",
           "message": "subscribe not enabled",
           "given": [
             "$.visibility.subscribe.enabled"
           ],
           "severity": "error",
           "created_at": "2024-05-22T17:19:02.000Z",
           "updated_at": "2024-05-22T17:24:59.000Z",
           "url": "https://my.manager.com/governance/orgs/myorg/rulesets/1.0.0-test-product/rules/ca6ef7d9-a503-498e-8f53-4e3aa35d086b",
           "then": [
             {
               "function": "pattern",
               "functionOptions": {
                 "notMatch": "/true"
               }
             }
           ]
         }
       ]
     }
     

  2. Log in to the toolkit as the owner or admin of the provider organization that owns the new ruleset.
  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 file name of the JSON file that contains the ruleset.