API paths carry a version
Every REST path includes a version segment, so a breaking change can ship next to the old contract.
MediumChecked automatically
- Applies to:
- Services with a REST API
- Rule id:
- api.versioned-paths
Why it matters
Sooner or later an API needs a breaking change. Without a version in the contract, the only options are breaking every caller at once or never changing. With one, the new contract ships beside the old, and callers move when they can.
How to apply it
- Put a major version in the path (
/v1/orders). It is visible in logs, easy to route on and hard to forget. - Bump it only for breaking changes. Adding a field or an endpoint is not one.
- When
/v2ships, announce an end date for/v1and watch its traffic drop before removing it. - If you version through a header or a media type instead, mark this rule not applicable and say so in the reason.
Example
GET /v1/orders/{id} and GET /v2/orders/{id} are served by the same service while callers migrate.
References
Checklists with this rule
Related agent skill: sync-communication