Versioning Policy
Spacetime exposes multiple APIs: NBI, Model, Provisioning, Scheduling and more.
To each API definition it’s assigned an independent version number, in the shorthand form (v1alpha, v1, v2), to communicate to API clients:
- the interface compatibility version.
- the stability level (see article: API Stability Levels).
To refer to a specific software release, capturing a defined set of features and bugfixes, please use the Spacetime Unified Version Number which is expressed in full SemVer format 14.12.1234566+buildinfo.
API Version negotiation
When multiple versions for the same API are supported, each version is accessible through a distinct endpoint, such as distinct subdomains. Example:
model-v0.CUSTOMER.spacetime.aalyria.commodel-v1alpha.CUSTOMER.spacetime.aalyria.com
For clients, this approach provides clear and predictable access to specific API versions.
For servers, the benefits include:
- making explicit the version requested by the client
- allow the release of new versions without disrupting existing infrastructure
- easy monitoring and control of the traffic received by each version
In addition to using distinct subdomains, each API must also include its major version number in the gRPC package name (or URL path when using REST). Example:
- gRPC package name:
com.aalyria.spacetime.model.v1.MethodName - REST Path:
/v1/resource/entity
This prevents the possibility that a client misconfiguration, or DNS error, can cause older clients to attempt to interact with incompatible API versions.