Overview

While predefined rulesets provide an excellent foundation, organizations often have unique standards and styling requirements for their APIs. APIGit’s custom rule profiles and governance policies let you tailor governance to your organization.

Creating or changing profiles and policies requires the Enterprise plan. On other plans the add and edit buttons are disabled. Custom profiles belong to an organization, and only organization owners can see its Governance tab.

Custom Rule Profiles

Custom rule profiles allow you to create specialized sets of rules that reflect your organization’s specific API standards and requirements.

To create and manage custom rule profiles:

1. Open your organization and select the Governance tab
2. Select API Governance and then Governance Profile
3. Click the plus icon next to Custom Rule Profiles (tooltip add custom rule profile) to add as many profiles as you need

Use the pencil next to Basic Info to change the name and description of a profile. Use the delete icon to remove a profile. Deleting a profile also deletes the policies that use it.

Edit Rules

Rules are stored as JSON. You can edit them in a form, or edit the JSON directly.

Select a profile and click the pencil next to Rules (tooltip edit rules) to open the Edit Rules dialog. It opens in the Form view:

1. Click Add Rule to add a rule, or click a rule to expand it
2. Set the severity, target spec format, name, message, description, target and validation of the rule
3. Use the icons on a rule to duplicate or delete it, and drag the handle of a collapsed rule to reorder it
4. Click Save

To edit the JSON, use the toggle in the upper right to switch to Source view (the code icon), then click Save.

The JSON has a rules object with one entry per rule, keyed by the rule name:

{
  "rules": {
    "acme-operation-summary": {
      "name": "acme-operation-summary",
      "id": "rule-1",
      "description": "Operations have a summary",
      "message": "Add a summary to {{path}}",
      "severity": "warn",
      "given": ["$.paths[*][get,put,post,delete,patch]"],
      "then": { "field": "summary", "function": "truthy" }
    }
  }
}

• name and id: Identify the rule
• description: A brief description of the rule
• message: The text shown in the results
• severity: error, warn, info, hint or off
• given: A path, or a list of paths, that selects the rule targets
• then: The field to check and the spectral function that validates it, or a list of these checks

In the form, Add target and Add check turn given and then into lists. A rule keeps a list after you remove entries from it.

A custom profile contains the rules you define and does not include the predefined rulesets. A rule that spectral can’t load is skipped when the profile runs, and if none of its rules load, the profile runs spectral’s spectral:oas rules instead, so check the results of a new rule on a real spec. The rules of a profile can be up to 2 MB.

Governance Policies

Governance policies determine which rule profiles apply to specific API repositories. This accommodates different standards across your API ecosystem, as repositories may serve different purposes with varying requirements.

To set up a policy:

1. Open your organization and select the Governance tab
2. Select API Governance and then Governance Policy
3. Click the plus icon next to Governance Policies (tooltip Create a new policy)
4. Fill in the Governance Policy dialog and click Save

The dialog has these fields:

• Profile: The governance profile to apply. You need to create a profile first.
• Format: OpenAPI
• Repository Scope: Turn on Apply to all repositories, or turn it off and pick repositories under Repositories:

A profile can be used by only one policy in an organization. Use the Edit button on a policy to change it.

Once a policy covers a repository, its profile appears under Custom Profiles in the ruleset dropdown of that repository’s Governance view.

Implementing Precision Governance

By combining custom rule profiles with targeted policies, you can:

• Apply different standards to internal vs. external-facing APIs
• Use stricter security rules on sensitive APIs
• Use graduated rules for APIs in different lifecycle stages
• Accommodate legacy APIs while holding new developments to modern standards