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.

Current API versions

As of Spacetime 15.103, Spacetime offers the following API:

• NBI v1alpha Deprecated North Bound API
• Model
  • v1alpha Replace the Modeling part of the deprecated NBI API.
  • v0 Uses NMTS 0.0.7
• Provisioning v1alpha Replace the Service Provisioning part of the NBI API.
• Scheduling v1alpha SouthBound API
• Telemetry v1alpha

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.com
• model-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.