Registration API documentation

Registration API documentation version v1.2

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

version: required(v1.2)

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

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

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Describes the Registration API base resource",
  "title": "Registration API base resource",
  "items": {
    "type": "string",
    "enum": [
      "resource/",
      "health/"
    ],
    "minItems": 2,
    "maxItems": 2,
    "uniqueItems": true
  }
}

Example:

[
    "resource/", 
    "health/"
]

Resource

/resource post

post

Create or update a registered resource

Request
Response

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Register a new resource or update an existing resource",
  "title": "Resource registration",
  "required": [
    "type",
    "data"
  ],
  "oneOf": [
    {
      "properties": {
        "type": {
          "description": "Singular form of the resource type to be registered",
          "type": "string",
          "enum": ["node"]
        },
        "data": {
          "$ref": "node.json"
        }
      }
    },
    {
      "properties": {
        "type": {
          "description": "Singular form of the resource type to be registered",
          "type": "string",
          "enum": ["device"]
        },
        "data": {
          "$ref": "device.json"
        }
      }
    },
    {
      "properties": {
        "type": {
          "description": "Singular form of the resource type to be registered",
          "type": "string",
          "enum": ["sender"]
        },
        "data": {
          "$ref": "sender.json"
        }
      }
    },
    {
      "properties": {
        "type": {
          "description": "Singular form of the resource type to be registered",
          "type": "string",
          "enum": ["receiver"]
        },
        "data": {
          "$ref": "receiver.json"
        }
      }
    },
    {
      "properties": {
        "type": {
          "description": "Singular form of the resource type to be registered",
          "type": "string",
          "enum": ["source"]
        },
        "data": {
          "$ref": "source.json"
        }
      }
    },
    {
      "properties": {
        "type": {
          "description": "Singular form of the resource type to be registered",
          "type": "string",
          "enum": ["flow"]
        },
        "data": {
          "$ref": "flow.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", "v1.2"],
            "endpoints": [
                {
                    "host": "172.29.80.65",
                    "port": 12345,
                    "protocol": "http"
                },
                {
                    "host": "172.29.80.65",
                    "port": 443,
                    "protocol": "https"
                }
            ]
        },
        "services": [
            {
                "href": "https://172.29.80.65:443/x-manufacturer/pipelinemanager/",
                "type": "urn:x-manufacturer:service:pipelinemanager"
            },
            {
                "href": "https://172.29.80.65:443/x-manufacturer/status/",
                "type": "urn:x-manufacturer:service:status"
            },
            {
                "href": "https://172.29.80.65:443/x-manufacturer/tally/",
                "type": "urn:x-manufacturer:service:tally"
            },
            {
                "href": "https://172.29.80.65:443/x-manufacturer/mdnsbridge/",
                "type": "urn:x-manufacturer:service:mdnsbridge"
            },
            {
                "href": "https://172.29.80.65:443/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
            }
        ],
        "interfaces": [
            {
                "name":"eth0",
                "chassis_id":"b3-cd-09-bb-9b-d8",
                "port_id":"b3-cd-09-bb-9b-d8"
            },
            {
                "name":"eth1",
                "chassis_id":"b3-cd-09-bb-9b-d8",
                "port_id":"b3-cd-09-bb-9b-d9"
            }
        ]
    }
}

HTTP status code 200

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

Headers

Location: required(string)

Example:

/x-nmos/registration/{version}/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Returning a registered resource from the Registration API",
  "title": "Registered resource",
  "oneOf": [
    {"$ref": "node.json"},
    {"$ref": "device.json"},
    {"$ref": "source.json"},
    {"$ref": "flow.json"},
    {"$ref": "sender.json"},
    {"$ref": "receiver.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", "v1.2"],
        "endpoints": [
            {
                "host": "172.29.80.65",
                "port": 12345,
                "protocol": "http"
            },
            {
                "host": "172.29.80.65",
                "port": 443,
                "protocol": "https"
            }
        ]
    },
    "services": [
        {
            "href": "https://172.29.80.65:443/x-manufacturer/pipelinemanager/",
            "type": "urn:x-manufacturer:service:pipelinemanager"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/status/",
            "type": "urn:x-manufacturer:service:status"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/tally/",
            "type": "urn:x-manufacturer:service:tally"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/mdnsbridge/",
            "type": "urn:x-manufacturer:service:mdnsbridge"
        },
        {
            "href": "https://172.29.80.65:443/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
        }
    ],
    "interfaces": [
        {
            "name":"eth0",
            "chassis_id":"b3-cd-09-bb-9b-d8",
            "port_id":"b3-cd-09-bb-9b-d8"
        },
        {
            "name":"eth1",
            "chassis_id":"b3-cd-09-bb-9b-d8",
            "port_id":"b3-cd-09-bb-9b-d9"
        }
    ]
}

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/{version}/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193/

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Returning a registered resource from the Registration API",
  "title": "Registered resource",
  "oneOf": [
    {"$ref": "node.json"},
    {"$ref": "device.json"},
    {"$ref": "source.json"},
    {"$ref": "flow.json"},
    {"$ref": "sender.json"},
    {"$ref": "receiver.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", "v1.2"],
        "endpoints": [
            {
                "host": "172.29.80.65",
                "port": 12345,
                "protocol": "http"
            },
            {
                "host": "172.29.80.65",
                "port": 443,
                "protocol": "https"
            }
        ]
    },
    "services": [
        {
            "href": "https://172.29.80.65:443/x-manufacturer/pipelinemanager/",
            "type": "urn:x-manufacturer:service:pipelinemanager"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/status/",
            "type": "urn:x-manufacturer:service:status"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/tally/",
            "type": "urn:x-manufacturer:service:tally"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/mdnsbridge/",
            "type": "urn:x-manufacturer:service:mdnsbridge"
        },
        {
            "href": "https://172.29.80.65:443/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
        }
    ],
    "interfaces": [
        {
            "name":"eth0",
            "chassis_id":"b3-cd-09-bb-9b-d8",
            "port_id":"b3-cd-09-bb-9b-d8"
        },
        {
            "name":"eth1",
            "chassis_id":"b3-cd-09-bb-9b-d8",
            "port_id":"b3-cd-09-bb-9b-d9"
        }
    ]
}

HTTP status code 400

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

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

/resource/{resourceType}/{resourceId} delete get

delete

Delete a registered resource

get

Show a registered resource (for debug use only)

Delete a registered resource

Request
Response

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}$)

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

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Show a registered resource (for debug use only)

Request
Response

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}$)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Returning a registered resource from the Registration API",
  "title": "Registered resource",
  "oneOf": [
    {"$ref": "node.json"},
    {"$ref": "device.json"},
    {"$ref": "source.json"},
    {"$ref": "flow.json"},
    {"$ref": "sender.json"},
    {"$ref": "receiver.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", "v1.2"],
        "endpoints": [
            {
                "host": "172.29.80.65",
                "port": 12345,
                "protocol": "http"
            },
            {
                "host": "172.29.80.65",
                "port": 443,
                "protocol": "https"
            }
        ]
    },
    "services": [
        {
            "href": "https://172.29.80.65:443/x-manufacturer/pipelinemanager/",
            "type": "urn:x-manufacturer:service:pipelinemanager"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/status/",
            "type": "urn:x-manufacturer:service:status"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/tally/",
            "type": "urn:x-manufacturer:service:tally"
        },
        {
            "href": "https://172.29.80.65:443/x-manufacturer/mdnsbridge/",
            "type": "urn:x-manufacturer:service:mdnsbridge"
        },
        {
            "href": "https://172.29.80.65:443/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
        }
    ],
    "interfaces": [
        {
            "name":"eth0",
            "chassis_id":"b3-cd-09-bb-9b-d8",
            "port_id":"b3-cd-09-bb-9b-d8"
        },
        {
            "name":"eth1",
            "chassis_id":"b3-cd-09-bb-9b-d8",
            "port_id":"b3-cd-09-bb-9b-d9"
        }
    ]
}

HTTP status code 404

Returned when the requested resource does not exist

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Node health

/health/nodes/{nodeId} post get

post

Update Node health

get

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

Update Node health

Request
Response

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}$)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Response to a request to update a resource's health",
  "title": "Heartbeat response",
  "required": [
    "health"
  ],
  "properties": {
    "health": {
      "description": "Timestamp indicating the time in seconds at which the server recorded the heartbeat",
      "type": "string",
      "pattern": "^[0-9]+$"
    }
  }
}

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

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

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

Request
Response

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}$)

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Response to a request to update a resource's health",
  "title": "Heartbeat response",
  "required": [
    "health"
  ],
  "properties": {
    "health": {
      "description": "Timestamp indicating the time in seconds at which the server recorded the heartbeat",
      "type": "string",
      "pattern": "^[0-9]+$"
    }
  }
}

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

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes the standard error response which is returned with HTTP codes 400 and above",
  "title": "Error response",
  "required": [
    "code",
    "error",
    "debug"
  ],
  "properties": {
    "code": {
      "description": "HTTP error code",
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "error": {
      "description": "Human readable message which is suitable for user interface display, and helpful to the user",
      "type": "string"
    },
    "debug": {
      "description": "Debug information which may assist a programmer working with the API",
      "type": ["null", "string"]
    }
  }
}

Documentation built at 05:12:15 CST on 2024-12-11.
(c) AMWA 2024. RAML/JSON licensed under Apache 2.0. Documentation licensed under CC BY-ND 4.0.

Registration API documentation version v1.2

Base

get /

HTTP status code 200

Body

Resource

post /resource

Body

HTTP status code 200

Headers

Body

HTTP status code 201

Headers

Body

HTTP status code 400

Body

delete /resource/{resourceType}/{resourceId}

URI Parameters

HTTP status code 204

HTTP status code 404

Body

get /resource/{resourceType}/{resourceId}

URI Parameters

HTTP status code 200

Body

HTTP status code 404

Body

Node health

post /health/nodes/{nodeId}

URI Parameters

HTTP status code 200

Body

HTTP status code 404

Body

get /health/nodes/{nodeId}

URI Parameters

HTTP status code 200

Body

HTTP status code 404

Body