API contract management
Track who consumes a route and gate changes to it.
By the OneEnv team · Last updated
What it is
An API route in OneEnv is owned by one service and has a name, URL and method. Other services relate to it in two independent ways: they inherit it (a read-only copy that tracks the owner) or an owned route tracks it as a source (the source's URL is copied into the owning route; one source is active at a time). Routes can also have request fields, documented URL relations to other routes, and links to error codes.
Why it matters
An API path or method change breaks callers silently. Recording who inherits the route lets the change be reviewed with its consumers listed, and lets each consumer approve or reject it.
What is governed
- Creating a route (staged; the route is private to its service until merge).
- Changing URL or method, archiving a route.
- Every create, update and delete of a request field.
- Not governed: renaming a route, deprecation and cron-schedule notes, URL relations, error mappings. These are documentation.
Breaking-change scoring
A method change, a path-shape change or a deletion is flagged as breaking and raises the impact score. A regex validation change is flagged conservatively. This is pattern detection on the recorded change, not analysis of your code or traffic.
Step by step: change a route
- Select or create a branch.
- Open the owning service's
APIstab (or API Studio) and edit the URL or method. - Review the staged change on the branch; the Change Review Center previews which services would be notified.
- Submit; an Owner or Admin merges; each inheriting service, and each route tracking this one as a source, gets a decision.
GET /v1/invoices owned by billing is inherited by web and tracked as an active source by mobile-bff. Changing the path to /v2/invoices on a branch produces a breaking-change flag and two pending decisions after merge.API Studio
API Studio is an editor for routes. The route list, request fields, mappings and your drafts are real. The Send button returns a canned response and test pass/fail is simulated; environments, history and activity panels are mock data. Do not treat Studio as a test runner.
Limitations
- OneEnv does not observe real traffic or read your source code.
- Consumers are only the ones recorded as inheriting or tracking the route.
- Cron fields are descriptive; nothing runs jobs.