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 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.
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
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
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",
"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
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",
"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
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",
"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
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"]
}
}
}
Delete a registered resource
Show a registered resource (for debug use only)
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"]
}
}
}
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",
"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
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
Update Node health
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"]
}
}
}
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"]
}
}
}