API contract change impact

When one team changes a route, the teams calling it usually learn from a failing request. OneEnv records which services depend on a route so the change can be reviewed and acknowledged first.

What is implemented

• An API route belongs to a service and has a url and method. Other services can inherit it (a read-only synced copy) or track it as a source for one of their own routes.
• Changing a route's url or method, or archiving it, is staged on a branch and only takes effect when the branch is reviewed and merged.
• On merge, every inheriting service and every service with a dependent source link gets an impact notification with the old and new value.
• Breaking-change detection flags method changes, path-shape changes and deletions, and tightened or added validation rules, and raises the impact score accordingly.
• Request fields are governed too: each field can map to a database column (inheriting that column's validation) or carry its own validation rule, and every add, edit or removal goes through the same branch review.
• Route-to-route dependencies and error-code mappings are documentation-only relations that appear in the dependency graph.

Example

The orders service changes the url of POST /v1/charges to POST /v2/charges. Three other services inherit that route. The rename is staged on a branch; reviewers see a breaking-change flag and a preview of the three affected services. After merge each consumer gets an impact card. Two approve and move to the new path; one rejects because it is not ready, and stays on the old path — visibly, in the audit trail.

Related: API and validation governance, the approval workflow.