Reviewing a Specification Change: See What It Touches Before You Approve

Overview

When a specification changes, the first question is not "is the new version valid?" It is "what will this touch?"

Shift-Left API answers that before you approve. It joins the change to everything attached to the APIs it replaces, so you approve knowing what is affected. It then tells you which tests are worth running. A person decides what to run, and nothing is run or rewritten for you.

This article covers the whole review. The mechanics of checking for changes and approving them are in API change detection.

What the impact panel shows

In the Review API Changes dialog, the impact panel lists what the change touches:

• tests
• mocks
• load tests
• workflows
• requirements attached to the APIs the change replaces
• the applications that use them
• the APIs that use a value from them (Uses a value from dependents)

A change that could break clients is marked Could break clients. A number you are not allowed to see is left out, never shown as zero.

When a change gives an API a new field or parameter, the panel and the API's Changes tab say that older tests cannot check it yet. A new API says that it has no tests, security checks or mocks yet.

Step 1 — Open the change

1. Open Project Settings and the Change Detection tab.
2. Select Check for Changes.
3. Select View Full Details & Review Changes.

Step 2 — Read the impact

In the Review API Changes dialog, read the impact panel before you decide. Pay most attention to anything marked Could break clients.

Step 3 — Run the tests this change affects (optional)

Under the impact panel is Run the tests this change affects.

1. Choose an environment in Run on. A production environment is listed as "production: never run from here".
2. Select Run N tests. The panel shows how many tests would run. If the list is capped, it says "the first N would run".
3. Confirm with Yes, run them. The confirmation reminds you that the tests call that environment's real servers.

You need permission to run tests manually. Without it you see the number and no button. Running tests is a person's click and is recorded in the audit log.

Step 4 — Approve or reject

Select Approve & Import or Reject. Approving creates new versions of the affected endpoints. It does not edit any existing test, so generate or repair tests for the new versions and run them.

If your project requires an approver, only people with the approve permission can approve. Anyone can reject. See API governance.

What changes after you approve

• Mocks. A mock of a changed API gets the May be out of date chip, with the note "The API this stands in for changed after the mock was made." Select I've checked it when you have looked. The mark never changes how the mock answers.
• Load tests and workflows. Ones that call a changed API get a note such as "An API it uses changed. Check that it still measures the right thing, then run it again." Nothing is run or edited. The note goes away once the item has run or you have looked.
• The API page. The Changes tab on the API page lists the change and any kept release verdicts.

Compare and follow changes in Discovery

With the API Discovery add-on, Discovery, then Changes, has four views.

What counts as breaking

The rules for breaking changes are the ones the product has always used. A rule set that judges requests and responses in opposite directions exists but is not switched on, so do not rely on it.

What this does not do

• It does not run tests after you approve a change. It tells you which tests are affected.
• It does not update tests when a specification changes. There are no self-healing tests. When a test fails, the opt-in AI repair can propose a fix for a person to review.
• It does not run tests on a production environment from the impact panel.

Troubleshooting

• The impact panel shows a dash. You may not read that part of the project.
• There is no Run N tests button. You need permission to run tests manually, and at least one affected test.
• The Changes views are missing from Discovery. Your licence does not include the API Discovery add-on.

Related articles

• API change detection
• Understanding mocks
• API governance
• API dependencies