Choose which APIs follow a workflow

Set policies, what each kind of change asks for, and the rules for restarts and expiry.

In short

A policy points a workflow at a set of APIs - by project, team, environment tier, criticality or by name. It also says what each kind of change asks for: the whole workflow again, some stages, or nothing - and when a verification expires.

Before you start

• Who: changing policies needs "Run API verification" (an Organization Admin or Manager).
• Plan: verification is part of plans that include API verification.
• First: a workflow to point the policy at (see /help/api-testing/verification-workflows).

Steps

1. Open "Ship" › "Verification", then "Workflows & policies", and create a policy.
2. Choose its workflow and limit it by project, team, responsible team, environment tier, criticality or specific APIs. A limit left empty includes everything.
3. For each kind of change, choose whether it repeats the whole workflow, some stages or nothing.
4. Set re-verification after a number of days, if you want, and save.

Result: the editor shows how many APIs the policy would govern, and those APIs show their verification status.

What a change asks for

When a verified API changes, the change is sorted by kind: contract, authentication, security, behavior, the request itself, its environment, or only name and description. The strictest answer wins.

A change that asks for nothing is still recorded, and the history shows the new version standing on the earlier verification.

Good to know

• Set an API's criticality in its request editor under Run settings.
• Environments are separate: an API verified in QA is not verified in Production until it goes through the process there. A check can require QA first.
• When several policies cover one API, the highest priority governs; on a tie, the one with the most limits, then the oldest.
• In an organization, by default, people who made a change cannot approve it, the person who asked for verification cannot approve it, and nobody decides two stages of one verification.
• After a rejection or a change, every stage runs again, or only the stages the change needs. Automated stages always run again.
• A policy can warn before a verification expires (seven days by default) and start the new one automatically.
• Editing a workflow or policy never changes a verification already started.
• If an automated check fails after full verification, it is flagged, or taken back so the API shows Verification failed, as the policy says.
• When someone leaves the organization, their reviews are flagged and the people who manage verification are told.

If something goes wrong

• The wrong policy governs an API: check the priorities; the highest priority wins.
• A small change restarted the whole workflow: change what that kind of change asks for in the policy.

Related

• /help/api-testing/verification-workflows
• /help/api-testing/verify-an-api