Registration API documentation version v1.3
http://example.api.com/x-nmos/registration/{version}
- version: required(v1.3)
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.
Further Documentation
Further normative documentation covering the behaviour of this API is contained in the docs folder of this repository.
Base
get
List of paths available from this API
get /
List of paths available from this API
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
options
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
post
Create or update a registered resource
post /resource
Create or update a registered resource
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"],
"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/{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"],
"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/{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"],
"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, missing mandatory attributes or breaches another condition which a Node is unlikely to be able to automatically correct.
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"]
}
}
}
HTTP status code 409
Returned when the resource already exists in the registry at a different API version. The correct API version is identified via the Location header.
Headers
- Location: required(string)
Example:
/x-nmos/registration/{version}/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193
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"]
}
}
}
options
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
delete
Delete a registered resource
get
Show a registered resource (for debug use only)
options /resource/{resourceType}/{resourceId}
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
delete /resource/{resourceType}/{resourceId}
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}$)
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"]
}
}
}
HTTP status code 409
Returned when the resource exists in the registry at a different API version. The correct API version is identified via the Location header.
Headers
- Location: required(string)
Example:
/x-nmos/registration/{version}/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193
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"]
}
}
}
get /resource/{resourceType}/{resourceId}
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}$)
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"],
"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
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"]
}
}
}
HTTP status code 409
Returned when the resource exists in the registry at a different API version. The correct API version is identified via the Location header.
Headers
- Location: required(string)
Example:
/x-nmos/registration/{version}/resource/nodes/3b8be755-08ff-452b-b217-c9151eb21193
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
options
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
post
Update Node health
get
Show a Node's health (for debug use only)
post /health/nodes/{nodeId}
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}$)
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"]
}
}
}
HTTP status code 409
Returned when the requested Node exists in the registry but at a different API version. The correct API version is identified via the Location header.
Headers
- Location: required(string)
Example:
/x-nmos/registration/{version}/health/nodes/3b8be755-08ff-452b-b217-c9151eb21193
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"]
}
}
}
get /health/nodes/{nodeId}
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}$)
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"]
}
}
}
HTTP status code 409
Returned when the requested Node exists in the registry but at a different API version. The correct API version is identified via the Location header.
Headers
- Location: required(string)
Example:
/x-nmos/registration/{version}/health/nodes/3b8be755-08ff-452b-b217-c9151eb21193
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"]
}
}
}