Verify an API

See where every API stands, start a verification and know what happens when it changes.

In short

"Verification > APIs" lists every API a policy covers, with its status, the ones needing someone first. Start a verification on one exact version of an API; after the first, every change that needs one starts it by itself.

Before you start

• Who: starting a verification needs Edit on the project. Deciding a stage needs you to be named as its reviewer.
• Plan: verification is part of plans that include API verification (Plan & usage › Features).
• First: a policy must cover the API, and the API must have run once so its contract is recorded.

Steps

1. Run the API once in the environment you want to verify so its contract is recorded (a policy can drop this).
2. Open it from "Ship" › "Verification" › "APIs", or choose "Verification: ..." in the request's menu.
3. Read "Next steps", then choose "Start verification".
4. Add a note for reviewers and name the people who built the change, so they cannot approve their own work.

Result: the first stages open and their reviewers are notified.

See where every API stands

The line under "Verification" says what it covers: every API in the workspace you work in, not one project - "Applies to every API in" your organization, or in your personal workspace. Filter by status, search by name, or show only APIs you answer for or whose verification expires soon. The same status appears beside each request on the project board and in the Catalog's Verification column. A verification forced through by an override shows (override).

When the API changes

• A change to what the request sends, its environment or its accepted contract records a new version. A verification on the old version stops, and a new one starts on the new version.
• A change the policy asks nothing for, such as a new description, keeps the API verified and says so in the history.
• A detected contract change waiting for review shows as a warning. Accepting it in API Changes records a new version.
• "Versions" compares any two versions, with what the policy would ask for. "History" shows who did what and why.

If something goes wrong

• An API is not listed: no policy covers it.
• "Start verification" is not offered: the contract is not recorded yet. Run the API once in that environment.
• The status went back to Verification required: the API changed in a way the policy asks to verify again.

Related

• /help/api-testing/review-a-verification
• /help/api-testing/verification-checks
• /help/api-testing/can-we-ship