Change an API contract

A route change, its consumers, and its risk score.

By the OneEnv team · Last updated 2026-10-15

Prerequisites

• A service that owns the route, and at least one other service that inherits it or tracks it as a source.
• Edit permission on the owning service.

Steps

1. Select or create a branch.
2. Open the owning service's APIs tab (or API Studio), edit the route's URL or method, and save. It is staged.
3. On the branch page check the Review Center. A method change, path-shape change or delete is flagged as breaking.
4. Submit and merge.
5. Inheriting services each approve (their copy re-syncs) or reject (their copy is marked diverged). Routes tracking this one as a source get a decision, and approving also updates the active source link.
6. Check the Dependency Graph if you want to see what else sits downstream.

Request fields

Every request-field create, update or delete is staged on a branch too, with the same invisible-until-merge behaviour for new fields. A field can point at a DB column, so it uses that column's validation.

Reading the risk

The breaking flag is a pattern on the recorded change. It cannot know about callers outside the recorded relationships, so list real consumers as inheritors or sources before you rely on the matrix.