Registration API documentation version v1.0

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

  • version: required(v1.0)

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.

mDNS Advertisement

Registration APIs MUST produce an mDNS advertisement of the type _nmos-registration._tcp

The mDNS advertisement MUST include a TXT record with key 'pri' and an integer value. 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. NB: In future versions of the specification it is likely that the 'priority' and 'weight' as specified by RFC 2782 will be used.

The IP address and port of the registration API MUST be identified via the mDNS advertisement, with the HTTP path then being resolved via the standard NMOS API path documentation.

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",
        "href": "http://172.29.80.65:12345/",
        "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"
    }
}

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.0/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/

Body

Media type: application/json

Example:

{
    "version": "1441973902:879053935",
    "hostname": "host1",
    "label": "host1",
    "href": "http://172.29.80.65:12345/",
    "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"
}

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.0/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/

Body

Media type: application/json

Example:

{
    "version": "1441973902:879053935",
    "hostname": "host1",
    "label": "host1",
    "href": "http://172.29.80.65:12345/",
    "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"
}

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",
    "href": "http://172.29.80.65:12345/",
    "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"
}

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