At a glance#
The rule depends on whose API it is.
| API | Version in | Example | Changes |
|---|---|---|---|
| A product a provider publishes | The path, as a major version | <product-slug>/v2/orders | A breaking change needs a new major version; a compatible change goes into the current one |
| A domain API of the platform (accounts, billing, catalogue and the other domain routes) | Nowhere: no version segment | catalogue/consumer/products | Additive changes only; a breaking change is blocked by the contract gate unless a maintainer accepts it on purpose |
info.version is a semantic version in both cases: MAJOR.MINOR.PATCH. For a provider API the major agrees with the path: info.version 2.4.0 goes with /v2/.
Provider APIs#
- The major version is the first segment of the path,
/v<n>/. The gateway creates the routes of a product version under that prefix, next to the routes of the other versions. - One specification describes one major version. A file with
/v1/and/v2/paths is split in two. - A version can be given in the first server URL instead of in each path, as long as the URL ends in
/v<n>. - The version is never carried in a header or in a query parameter.
A change is breaking when it can make a working client fail: removing or renaming a property, changing a type, tightening validation, removing an enum value, or changing the status code of an existing case. Adding a property, a header, an optional parameter or an enum value to a response is not breaking. The written definition is on Versions and breaking changes.
Platform domain APIs#
Each domain specification is served under its domain route and has no version segment: the route is the address, the contract is kept additive. The platform lints its own specifications with the platform profile, which refuses a /v<n>/ segment there and requires a semantic info.version. A breaking change is caught when the contract is changed, before it merges.
A major version is retired with at least 90 days' notice, announced by the Deprecation and Sunset response headers, and its routes stay in place until the sunset date.
Today a deprecated major version stays available for 30 days after the platform approves its deprecation.
Checked by#
| Rule | Severity | Profile | Checks |
|---|---|---|---|
api360-version-info | error | both | info.version is a semantic version |
api360-version-in-path | error | provider | Every path is under /v<n>/, or the server URL ends in /v<n>; the major agrees with info.version; one major per file |
api360-platform-unversioned-paths | error | platform | No path starts with /v<n> |
See also#
- Deprecation: how a retiring operation announces itself.
- Create a version and deprecate one: the provider's steps.
- Linting a specification: the two profiles.