Versioning (#3101)
API versioning at Kong is done via the URL. This makes selecting a version an explicit choice, and makes it easy to see which version of an API is being used in logs etc.
Public APIs
When exposing an API publicly, the route must start with the version and resource name [1]. Whilst service name could be useful for routing, Kong Gateway can route based on resource names and we have chosen to add routing complexity internally for a better external experience.
Valid examples:
/v1/users/v1/teams/v2/runtime-groups
Kong APIs are versioned per resource, not globally. If an API is not resource based, the entire API is versioned together.
The API version does not form part of the base URL for an API consumer. This allows us to serve /v1/users and /v2/runtime-groups at the same time, without bumping /users to v2.
[1] KPortal APIs will start with /api, then the version and resource name due to a product requirement to serve both the API and UI from a single (custom) domain
Internal APIs
We recommend that the service name is not a part of your internal routing, and that strip_path is used by Kong to remove the service prefix before passing to the upstream API.
The version must come after the service prefix, but before any resource names if a service prefix exists.
The service prefix may contain more than one URL segment.
Examples:
/kauth/v1/users/kauth/v1/teams/other/api/v2/projects
Sunsetting an API
Any GA API must provide a 6 month deprecation window before it can be removed. This will be communicated via the Sunset header and through public documentation.
For on-premise APIs, removal must coincide with a major release of a product.
Internal APIs may be deprecated as soon as there is a new API that enables all existing use cases. The API may be switched off when there is no more internal usage.
Beta releases
New APIs are subject to rapid iteration, and sometimes we need to break backwards compatibility. In order to do this without a painful deprecation period, we may offer v0 APIs whilst prototyping new services.
The initial version of an API would be v0.1, followed by v0.2 etc. Beta APIs must provide a 30 day deprecation window before removal.
Deprecating APIs for a new service
API versions must always increase. This means that if we're currently running kauth/v1/users, we cannot replace that with users-service/v1/users. We must ship the new version as users-service/v2/users. The service path is an internal implementation detail.
If an API moves betweeen services and is 100% compatible, then you may keep the same version number.
Unversioned APIs
New unversioned APIs are not permitted. Existing unversioned APIs may continue to be improved, and are implicitly v1. Any future version of unversioned APIs must start at v2.
Multiple versions
A single release may support multiple versions of an API. This allows consumers to upgrade their tooling gradually, endpoint by endpoint.
API versions vs. spec versions
An API's version is exposed in user documentation and in the API URL. In a URL, the version always begins with "v"; for example, "v1" (a GA version) or "v0.1" (a beta version).
A spec's version is exposed in its info.version field. It adheres to semantic versioning; for example, "0.1.0" or "1.0.0". When a spec is updated, its patch version should be incremented. If the change includes additions, the spec's minor version should be incremented and its patch version reset to 0.