Discovery: Registered Operation
←Discovery · Index↑ · Discovery - Peer to Peer Operation→
This document describes usage of NMOS APIs for discovery in cases where where a distributed registry is available.
Registration API
DNS-SD Advertisement
The preferred method of Registration API advertisement is via unicast DNS-SD advertisement of the type _nmos-register._tcp. Registration APIs MUST additionally be capable of producing an mDNS advertisement. The Registry MAY provide a user-configurable method to disable this advertisement.
Registration APIs supporting versions v1.2 and below MUST additionally be capable of producing an mDNS advertisement of type _nmos-registration._tcp. The Registry MAY provide a user-configurable method to disable this advertisement.
Note: RFC 6763 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.
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.
DNS-SD TXT Records
api_proto
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.
api_ver
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.
api_auth
The DNS-SD advertisement MUST be accompanied by a TXT record of name api_auth with a value of either true or false dependent on whether authorization is needed for Registration API requests.
pri
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 (see 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.
Client Interaction Procedure
-
Node comes online
-
Node scans for an active Registration API on the network using unicast and/or multicast DNS service discovery (type
_nmos-register._tcp) as described in the Discovery document.- Nodes which support v1.2 and earlier versions MUST additionally browse for the deprecated service type
_nmos-registration._tcp.
- Nodes which support v1.2 and earlier versions MUST additionally browse for the deprecated service type
-
Given multiple returned Registration APIs, the Node orders these based on their advertised priority (TXT
pri), filtering out any APIs which do not support the desired API version, protocol and authorization mode (TXTapi_ver,api_protoandapi_auth).- Where a Node supports multiple API versions simultaneously, see the Upgrade Path for additional requirements in filtering the discovered API list.
-
The Node selects a Registration API to use based on the priority, and a random selection if multiple Registration APIs of the same API version with the same priority are identified.
-
Node proceeds to register its resources with the selected Registration API.
If the chosen Registration API does not respond correctly at any time, another Registration API SHOULD be selected from the discovered list. If no further Registration APIs are available or TTLs on advertised services have expired, a re-query MAY be performed.
If no Registration APIs are advertised on a network, the Node SHOULD assume peer-to-peer operation unless configured otherwise. The REQUIRED TXT record advertisements for this mode are described in the Peer-to-Peer Operation documentation.
Query API
DNS-SD Advertisement
The preferred method of Query API advertisement is via unicast DNS-SD advertisement of the type _nmos-query._tcp. Query APIs MUST additionally be capable of producing an mDNS advertisement. The Registry MAY provide a user-configurable method to disable this advertisement.
The IP address and port of the Query 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.
DNS-SD TXT Records
api_proto
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 Query API web server.
api_ver
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.
api_auth
The DNS-SD advertisement MUST be accompanied by a TXT record of name api_auth with a value of either true or false dependent on whether authorization is needed in order to interact with the Query API or not.
pri
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 (see 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 Query API (zero being the highest priority). Values 100+ are reserved for development work to avoid colliding with a live system.
Client Interaction Procedure
-
Node (or control interface) comes online
-
Node scans for an active Query API on the network using unicast and/or multicast DNS service discovery (type
_nmos-query._tcp) as described in the Discovery document. -
Given multiple returned Query APIs, the Node orders these based on their advertised priority (TXT
pri), filtering out any APIs which do not support the desired API version, protocol and authorization mode (TXTapi_ver,api_protoandapi_auth).- Where a Node supports multiple API versions simultaneously, see the Upgrade Path for additional requirements in filtering the discovered API list.
-
The Node selects a Query API to use based on the priority, and a random selection if multiple Query APIs of the same version with the same priority are identified.
-
Node requests data from the selected Query API.
If the chosen Query API does not respond correctly at any time, another Query API SHOULD be selected from the discovered list. If no further Query APIs are available or TTLs on advertised services have expired, a re-query MAY be performed.
If no Query APIs are advertised on a network, the Node SHOULD assume peer-to-peer operation (if supported) unless configured otherwise.