API Governance: Lifecycle, Approvers, Design Standards, Policies and Risks

Overview

API governance is where a team says how its APIs are meant to be run, and checks that they are. It covers:

• where each API is in its life
• who must approve a specification change
• the design standards a specification must meet
• policies that every API must meet
• a register of the risks you chose to live with

Governance records, checks and reports. It never changes an API, never runs a test and never accepts a risk for you. Every rule is opt-in and starts off, so a project that has chosen none is never refused anything. Governance can enforce your rules once you switch them on. It does not enforce anything by default.

Before you begin

• Open Governance from the header. If you do not see it, tick Governance in your account menu under the header tabs. If it is still missing, your plan does not include it or it is switched off for your installation.
• Role defaults: Contributors, Reviewers and Readers can view governance. Administrators can manage it. Administrators and Reviewers can approve changes. An administrator can change these under Role permissions.
• Someone who can only look sees every number and none of the buttons.

Step 1 — Start from "What needs doing"

The Overview tab opens with What needs doing in this project, in three parts:

• Needs your action. What to do now, most urgent first, each with a button to the tab where it is done. For example, APIs that break a policy, a risk acceptance that has ended, design rules a specification breaks, or APIs with no lifecycle state.
• Not set up yet (optional). Parts of governance this project does not use yet. They are never shown as failures.
• In place. What is already set up and working.

Step 2 — Set each API's lifecycle

Open Lifecycle. Every API is Draft, Active, Deprecated or Retired, once someone has said so.

• An API nobody has classified shows as Not set. It is counted on its own and is still treated as in use.
• A person sets the state. The product only suggests.
• Deprecated means the API still works but is on its way out. Give it a retirement date so users have notice. A project can make the date compulsory.
• Retired means it has left the working views. Nothing is deleted: tests, runs, findings, mocks and history stay, and you can bring it back.
• An API cannot go straight from Active to Retired. Deprecate it first.
• Retiring before the retirement date needs a confirmation, and the early retirement is recorded.

Each row says where its state came from: Set by a person, From the specification or Nobody has said.

When you deprecate or retire an API, the owner is told, and any mock of that API is marked May be out of date. No mock is changed or switched off.

Under the list, Worth a look suggests APIs that Discovery has not seen for a while. It says how many APIs it could judge out of how many there are. Nothing changes unless you choose to.

Step 3 — Choose project rules

Open Project rules. Every rule starts off. You can switch on:

• Changes to the specification need an approver. Only people with the approve permission, or the owner of every API the change modifies or removes, can approve. Anyone can still reject.
• Most versions live at once. Approving a change that would go over the limit is refused, and the message names the oldest version to retire first.
• Deprecating an API needs a retirement date.
• The specification's version must be a real version number, such as 2.1.0 and higher than the last one approved. This applies to OpenAPI and Swagger.
• Suggest retiring an API not seen for a number of days.

When a rule stops an approval, the review screen says so before you click. The refusal happens before anything is imported, so the change stays waiting.

The owner of an API is the name typed in its owner field. It is matched to a person by email address, or by name when only one person has it. A name that matches nobody, or two people, reaches nobody, and the product says so.

Step 4 — Hold the specification to your design standards

Open Design standards. Four rulesets are included: Documentation, Naming, Design and Standard, which is all three. You can read every shipped rule but not change it. To change one, start your own from it.

Select Check the specification now. It reads the project's stored OpenAPI or Swagger document and shows:

• the verdict: Rules met, Warnings, Rules broken or Not checked
• how many rules were broken out of how many ran
• the findings, grouped by rule, each with where it is

Rules met says the rules were met. It does not say the API is well designed or secure. A project with no stored OpenAPI or Swagger document is Not checked, with the reason.

Write your own rules

Select Write your own to write rules in JSON or YAML in the style Spectral uses. Use Check the rules to find mistakes by rule name, and Try it on this project to see what a draft would say without saving it. A ruleset that fails the checks cannot be saved.

Shift-Left API reads these rules with its own engine, which understands a defined set of rule functions. It is Spectral-style, not Spectral. A ruleset that extends Spectral's own rulesets, or uses filters or functions the engine does not know, is refused with the reason. A rule that cannot be evaluated is listed as could not be evaluated, and the check reads Not fully checked. It is never counted as a pass.

Step 5 — Write policies

Open Policies. A policy says what must be true of some of your APIs. For example, APIs that look like they return personal data must require sign-in and must have passed the object-level access check.

A policy is built from a list of facts the product knows, such as whether the specification says callers must sign in or how many tests an API has. There is no free text and no code. "Looks like it returns personal data" is a guess from field names and tags, and the violation lists the names it found.

Policies are checked every night and when you select Check now. An API that breaks one appears under APIs that break a policy, with what was needed and what was found.

You can allow a violation by giving a reason of at least ten characters, and an end date within a year. When the date passes, the violation opens again.

Step 6 — Keep a risk register

Open Risks. Each API shows the worst of three kinds of risk:

• Security, from its security risk rating. You see this only if you can see security findings. Otherwise the list says it is partial.
• Pending change, a specification change waiting for review that could break the people who use the API.
• Checks, gaps in what is checked. One gap is low, two are medium, three or more are high.

You can accept a risk with a reason and an end date. The date can be up to a year away, and up to 90 days for a critical risk. Your name, the reason and the date are kept. An accepted risk leaves the open list only while the acceptance is in force and the risk is no worse than when you accepted it. When the date passes, or the risk gets worse, it is open again. You can withdraw an acceptance at any time.

Documentation and duplicates

• How fully each API is documented counts documentation items in place, such as a description, parameters and an error response. It says "5 of 7", never a percentage. It is a report and does not change how tests are generated.
• The same operation more than once shows duplicates in this project and equivalents in other projects you can open.
• Who answers for each API shows how many named owners reach a person.

Who sees which API

You can list the teams that see an API in the governance and API views. This narrows what people see. It is a view, not a lock: anyone with access to the project can still open the API elsewhere, and people who manage governance always see everything. Per-API permissions are not available.

Exports

You can export the audit log, the security compliance view and the requirements traceability matrix as CSV or PDF. An export is one file of what the screen shows, and large tables are truncated and flagged. It is not a compliance attestation. See Audit logs.

What is not included

• Spectral itself. Governance reads Spectral-style rulesets with its own engine.
• Governance for the Citizen Developer plan.
• Design standards for protocols other than OpenAPI and Swagger. They read Not checked there. Lifecycle and policies still work.
• Permissions for each individual API.
• Automatic application of any suggestion. A person always decides.

Troubleshooting

• Governance is missing from the header. Tick it in your account menu. If it is not offered, your plan does not include it.
• A refusal on approval. A project rule stopped it. The review screen names the rule.
• A risk reappeared. The acceptance ended, or the risk got worse.

Related articles

• Review a specification change
• The API page: quality evidence for one API
• Release verdict
• Role permissions