Catch breaking changes in a new API version

Compare a new OpenAPI version with the project's contract, see what breaks and what it touches, and let verification decide it.

In short

Give {{brand}} a new OpenAPI version and it compares it with the project's contract: what breaks callers, what needs review and what is safe. It lists what the change touches, runs the affected suites, files one card, and keeps one timeline per endpoint and a changelog.

Before you start

• Who: comparing a version and deciding a change need Edit on the project; anyone who can open it reads.
• Plan: API changes come with plans that include change intelligence (Plan & usage › Features).
• First: an OpenAPI 3 or Swagger 2 file or address.

Steps

1. Open API Tester › "Watch" › "API changes" with a project open.
2. Choose "Try a sample change". The sandbox bookstore's version 1 becomes the contract and its version 2 is compared with it.
3. Open the change: a removed field and a newly required one break callers, and a deprecated parameter gets a sunset.
4. Mark it verified, or dismiss the version.

1. Choose "Compare a new version".
2. Upload an OpenAPI 3 or Swagger 2 file, or give the document's address.
3. Open the change and read its verdict and what it touches.

Result: the change is classified, and what it touches is listed and acted on by itself.

What happens next by itself

• What it touches: saved requests, suites and monitors that call a changed endpoint, Designer workflows that use the service, UI tests that reach its sites, and linked cards. You only see what you may open.
• Before and after: up to three affected suites run on Production and on Staging, and the answers are set side by side.
• Verification: when your workspace verifies API changes, each touched API starts its verification under the policy, and the change is verified once all of them are.
• Work: one API change card on the board connected to the project, with a checklist of tests to update. It turns green when the change is verified, and moves to done with a comment when a newer version replaces it or someone dismisses it.
• Owners: the people responsible for the touched endpoints get a notice.

One timeline per endpoint

In a change, choose "Timeline" beside an endpoint. It lists every change that touched it, oldest first. Each change shows when it was detected and how it was classified, what it touched, and the before and after. It also shows each verification and reviewer's decision with its evidence, the card, who decided, and the deprecation marks with their reminders. Under "More", export it as Markdown or CSV.

Changes seen in runs

"Seen in runs" lists what runs and monitor checks saw change in an endpoint, without a new API document: a field that appeared or went away, a new status code, a slower response. It shows the open project, or every project when none is open. Accept a change to make it the endpoint's new baseline, or ignore it. When some wait, the changes list says how many and "Review them" opens them.

The changelog and deprecations

"Changelog" lists every version that became the contract, newest first. Each is sorted for the people who call the API: breaking changes, changes to check, added, deprecated, and the notes on how to update. Export it as Markdown for a release note. When a breaking change is verified, the people who depend on the API are told.

"Deprecations" lists the endpoints and fields on their way out. Mark one with the day it stops working, or let the API document mark it with its deprecated flag and an x-sunset date. A run that still uses it gets a warning, and the people who depend on it are reminded 30, 7 and 1 days before, and on the day.

Good to know

• The first document becomes the project's contract. Until then, the project's own saved requests stand for it.
• The sample is offered while the project has no contract of its own yet, so it never mixes with your real API.
• While verifications decide a change, "Mark verified" is not offered: review the APIs in Verification, or dismiss the version. With no policy covering them, a person with change rights marks it verified.
• "Notes for the changelog" holds the change in plain words, how callers update and the tests to update. Write them yourself, or choose "Draft with AI"; nothing an AI wrote is kept until you choose "Approve and save".
• Only people who can open the project see the changelog.

If something goes wrong

• "The file is not a readable OpenAPI or Swagger document.": upload the JSON or YAML document itself.
• "Mark verified" is missing: verifications decide this change. See /help/api-testing/verification-workflows.
• The sample is not offered: the project already has a contract.
• "This project already has an API contract, so the sample change would mix with it. Compare your own new version instead."
• "Choose the OpenAPI file to compare." and "The address answered with an empty document.": give a file or an address that holds a document.
• "The document describes no operations to compare." means the file holds none. A message that begins "The document describes more than" means it is too large: compare a smaller one.
• "This change was already decided, or a newer version replaced it.": reload the page.
• "The verification of this change decides it. Review it in Verification, or dismiss the change."
• "The sunset date must be today or later.": choose the day the endpoint stops working.

Related

• /help/api-testing/change-intelligence
• /help/api-testing/verification-workflows
• /help/api-testing/tests-after-a-deploy