Networked Media Open Specifications
DOCS APIS EXAMPLES VERSIONS IS BCP MS INFO REG DEVEL SEARCH

Upgrade Path

←Data Model - Identifier Mapping · Index↑

As is common with web APIs, over time changes will be made to support new use cases and deprecate old ways of working. The NMOS APIs are no different, and have been designed to permit in-service upgrades across a facility which may be running large amounts of equipment with support for different versions of these specifications.

API versioning is specified in the APIs documentation, with procedures for handling upgrades described below.

Requirements for Nodes (Node APIs)

Implementers of the Node API must support at least one API version, and may support more than one at a time. Note however that a Node must only perform interactions with a Registration API at a single version. Nodes implementing multiple API versions may provide a user-configurable choice for which API version to register and/or query using.

Registrations with a Registration API must only proceed if the Node API version implemented exactly matches the API version used by the Registration API.

Requirements for Registries (Registration and Query APIs)

Implementers of the Registration and Query API must support at least one API version. It is however strongly recommended that Registration and Query APIs fully support at least two and preferably more consecutive API versions (if released). In doing so, facilities which include a large number of Nodes may stagger their equipment upgrades whilst maintaining compatibility with a single registry.

When supporting multiple API versions, Query APIs must provide translations of resources for backwards compatibility. For example, if the registry contains a mixture of v1.0 and v1.1 resources, a v1.0 Query API must provide a response containing all of these resources by removing keys from v1.1 resources which are not present in v1.0.

Query APIs are not required to provide for forwards compatibility as it may be impossible to generate data for new attributes in schemas. Query APIs should however allow clients to request older data than the requested minor API version by using the ?query.downgrade= query parameter (see Query API documentation for examples).

Performing Upgrades

The following procedure is suggested for a live system which needs to migrate between API versions:

←Data Model - Identifier Mapping · Index↑