Registration API documentation version v1.1

http://example.api.com/x-nmos/registration/{version}

  • version: required(v1.1)

Overview

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.

DNS-SD Advertisement

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.

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.

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' 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.

Versioning

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.

Base

get

get

List of paths available from this API

List of paths available from this API

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

Example:

[
    "resource/", 
    "health/"
]

Resource

post

post

Create or update a registered resource

Create or update a registered resource

Body

Media type: application/json

Example:

{
    "type": "node",
    "data": {
        "version": "1441973902:879053935",
        "hostname": "host1",
        "label": "host1",
        "description": "host1",
        "tags": {},
        "href": "http://172.29.80.65:12345/",
        "api": {
            "versions": ["v1.0", "v1.1"],
            "endpoints": [
                {
                    "host": "172.29.80.65",
                    "port": 12345,
                    "protocol": "http"
                },
                {
                    "host": "172.29.80.65",
                    "port": 443,
                    "protocol": "https"
                }
            ]
        },
        "services": [
            {
                "href": "http://172.29.80.65:12345/x-manufacturer/pipelinemanager/",
                "type": "urn:x-manufacturer:service:pipelinemanager"
            },
            {
                "href": "http://172.29.80.65:12345/x-manufacturer/status/",
                "type": "urn:x-manufacturer:service:status"
            },
            {
                "href": "http://172.29.80.65:12345/x-manufacturer/tally/",
                "type": "urn:x-manufacturer:service:tally"
            },
            {
                "href": "http://172.29.80.65:12345/x-manufacturer/mdnsbridge/",
                "type": "urn:x-manufacturer:service:mdnsbridge"
            },
            {
                "href": "http://172.29.80.65:12345/x-manufacturer/storequery/",
                "type": "urn:x-manufacturer:service:storequery"
            }
        ],
        "caps": {},
        "id": "3b8be755-08ff-452b-b217-c9151eb21193",
        "clocks": [
            {
                "name": "clk0",
                "ref_type":"internal"
            },
            {
                "name": "clk1",
                "ref_type":"ptp",
                "traceable": true,
                "version": "IEEE1588-2008",
                "gmid": "08-00-11-ff-fe-21-e1-b0",
                "locked": true
            }
        ]
    }
}

HTTP status code 200

The expected response for an update operation on an existing registered resource

Headers

  • Location: required(string)

    Example:

    /x-nmos/registration/v1.1/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/

Body

Media type: application/json

Example:

{
    "version": "1441973902:879053935",
    "hostname": "host1",
    "label": "host1",
    "description": "host1",
    "tags": {},
    "href": "http://172.29.80.65:12345/",
    "api": {
        "versions": ["v1.0", "v1.1"],
        "endpoints": [
            {
                "host": "172.29.80.65",
                "port": 12345,
                "protocol": "http"
            },
            {
                "host": "172.29.80.65",
                "port": 443,
                "protocol": "https"
            }
        ]
    },
    "services": [
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/pipelinemanager/",
            "type": "urn:x-manufacturer:service:pipelinemanager"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/status/",
            "type": "urn:x-manufacturer:service:status"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/tally/",
            "type": "urn:x-manufacturer:service:tally"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/mdnsbridge/",
            "type": "urn:x-manufacturer:service:mdnsbridge"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/storequery/",
            "type": "urn:x-manufacturer:service:storequery"
        }
    ],
    "caps": {},
    "id": "3b8be755-08ff-452b-b217-c9151eb21193",
    "clocks": [
        {
            "name": "clk0",
            "ref_type":"internal"
        },
        {
            "name": "clk1",
            "ref_type":"ptp",
            "traceable": true,
            "version": "IEEE1588-2008",
            "gmid": "08-00-11-ff-fe-21-e1-b0",
            "locked": true
        }
    ]
}

HTTP status code 201

The expected response for a create operation performed for a previously unregistered resource

Headers

  • Location: required(string)

    Example:

    /x-nmos/registration/v1.1/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/

Body

Media type: application/json

Example:

{
    "version": "1441973902:879053935",
    "hostname": "host1",
    "label": "host1",
    "description": "host1",
    "tags": {},
    "href": "http://172.29.80.65:12345/",
    "api": {
        "versions": ["v1.0", "v1.1"],
        "endpoints": [
            {
                "host": "172.29.80.65",
                "port": 12345,
                "protocol": "http"
            },
            {
                "host": "172.29.80.65",
                "port": 443,
                "protocol": "https"
            }
        ]
    },
    "services": [
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/pipelinemanager/",
            "type": "urn:x-manufacturer:service:pipelinemanager"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/status/",
            "type": "urn:x-manufacturer:service:status"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/tally/",
            "type": "urn:x-manufacturer:service:tally"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/mdnsbridge/",
            "type": "urn:x-manufacturer:service:mdnsbridge"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/storequery/",
            "type": "urn:x-manufacturer:service:storequery"
        }
    ],
    "caps": {},
    "id": "3b8be755-08ff-452b-b217-c9151eb21193",
    "clocks": [
        {
            "name": "clk0",
            "ref_type":"internal"
        },
        {
            "name": "clk1",
            "ref_type":"ptp",
            "traceable": true,
            "version": "IEEE1588-2008",
            "gmid": "08-00-11-ff-fe-21-e1-b0",
            "locked": true
        }
    ]
}

HTTP status code 400

Returned when the POST request is incorrectly formatted or missing mandatory attributes

Body

Media type: application/json

delete get

delete

Delete a registered resource

get

Show a registered resource (for debug use only)

Delete a registered resource

URI Parameters

  • resourceType: required(one of nodes, devices, sources, flows, senders, receivers)
  • resourceId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

Body

Media type: application/json

HTTP status code 204

The expected response, indicating 'No Content' following the DELETE

HTTP status code 404

Returned when the requested resource does not exist

Body

Media type: application/json

Show a registered resource (for debug use only)

URI Parameters

  • resourceType: required(one of nodes, devices, sources, flows, senders, receivers)
  • resourceId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

Example:

{
    "version": "1441973902:879053935",
    "hostname": "host1",
    "label": "host1",
    "description": "host1",
    "tags": {},
    "href": "http://172.29.80.65:12345/",
    "api": {
        "versions": ["v1.0", "v1.1"],
        "endpoints": [
            {
                "host": "172.29.80.65",
                "port": 12345,
                "protocol": "http"
            },
            {
                "host": "172.29.80.65",
                "port": 443,
                "protocol": "https"
            }
        ]
    },
    "services": [
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/pipelinemanager/",
            "type": "urn:x-manufacturer:service:pipelinemanager"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/status/",
            "type": "urn:x-manufacturer:service:status"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/tally/",
            "type": "urn:x-manufacturer:service:tally"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/mdnsbridge/",
            "type": "urn:x-manufacturer:service:mdnsbridge"
        },
        {
            "href": "http://172.29.80.65:12345/x-manufacturer/storequery/",
            "type": "urn:x-manufacturer:service:storequery"
        }
    ],
    "caps": {},
    "id": "3b8be755-08ff-452b-b217-c9151eb21193",
    "clocks": [
        {
            "name": "clk0",
            "ref_type":"internal"
        },
        {
            "name": "clk1",
            "ref_type":"ptp",
            "traceable": true,
            "version": "IEEE1588-2008",
            "gmid": "08-00-11-ff-fe-21-e1-b0",
            "locked": true
        }
    ]
}

HTTP status code 404

Returned when the requested resource does not exist

Body

Media type: application/json

Node health

post get

post

Update Node health

get

Show a Node's health (for debug use only)

Update Node health

URI Parameters

  • nodeId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

Example:

{
    "health": "1441974485"
}

HTTP status code 404

Returned when the requested Node does not exist or has been garbage collected

Body

Media type: application/json

Show a Node's health (for debug use only)

URI Parameters

  • nodeId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

Example:

{
    "health": "1441974485"
}

HTTP status code 404

Returned when the requested Node does not exist or has been garbage collected

Body

Media type: application/json