Registration API documentation version v1.2
- version: required(v1.2)
The Registration API is exposed by NMOS discovery Nodes. It is used to publish data to the distributed registry, which can then be queried via the Query API. In smaller deployments where no distributed registry is available, the Registration API is not used and discovery responsibilities fall to individual Nodes which choose to implement Peer to Peer specification. The Registration API is a Write Only API.
Registration APIs MUST produce an mDNS advertisement of the type _nmos-registration._tcp. This MAY be accompanied by a unicast DNS announcement of the same type. note: RFC6763 Section 7.2 specifies that the maximum service name length for an mDNS advertisement is 16 characters when including the leading underscore, but "_nmos-registration" is 18 characters. Implementers of IS-04 v1.2 and below are advised to consult the v1.3 documentation for an additional service type which can be used to resolve this issue. Use of this additional service type requires that any v1.2 and earlier Nodes are also updated to support browsing for it.
The IP address and port of the Registration API MUST be identified via the DNS-SD advertisement, with the full HTTP path then being resolved via the standard NMOS API path documentation.
Multiple DNS-SD advertisements for the same API are permitted where the API is exposed via multiple ports and/or protocols.
The DNS-SD advertisement MUST be accompanied by a TXT record of name 'api_proto' with a value of either 'http' or 'https' dependent on the protocol in use by the Registration API web server.
The DNS-SD advertisement MUST be accompanied by a TXT record of name 'api_ver'. The value of this TXT record is a comma separated list of API versions supported by the server. For example: 'v1.0,v1.1,v2.0'. There should be no whitespace between commas, and versions should be listed in ascending order.
The DNS-SD advertisement MUST include a TXT record with key 'pri' and an integer value. Servers MAY additionally represent a matching priority via the DNS-SD SRV record 'priority' and 'weight' as defined in RFC 2782. The TXT record should be used in favour to the SRV priority and weight where these values differ in order to overcome issues in the Bonjour and Avahi implementations. Values 0 to 99 correspond to an active NMOS Registration API (zero being the highest priority). Values 100+ are reserved for development work to avoid colliding with a live system.
A Registration API may support multiple API versions at one time, provided data exposed from each of these versioned endpoints matches the schema for that API version. A Node registering with a Registration API should do so using only one version at a time, which should be the highest version which both the Node and the Registration API support. See the [APIs](../docs/2.0. APIs.md) and [Upgrade Path](../docs/6.0. Upgrade Path.md) documentation for more details.