Node API documentation version v1.2
http://example.api.com/x-nmos/node/{version}
- version: required(v1.2)
Overview
The Node API is exposed by each NMOS Node in a system, regardless of whether it is possible for that Node to provide NMOS resources such as Flows, Sources etc. Data exposed by the Node API is used to populate the (distributed) registry via the Registration API. In smaller deployments the Node API is fetched from directly as required by Nodes which implement the Peer to Peer specification.
DNS-SD Advertisement
Node APIs MUST produce an mDNS advertisement of the type _nmos-node._tcp. This MAY be accompanied by a unicast DNS announcement of the same type. Note that peer to peer mode and Node mDNS announcements are optional from v1.3 of the specification.
The IP address and port of the Node 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' (lower-case) dependent on the protocol in use by the Node 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.
ver_
When a Node is unable to locate or successfully register with a Registration API it MUST additionally advertise the following mDNS TXT records as part of its Node advertisement. If a Node is successfully registered with a Registration API it MUST withdraw advertisements of these TXT records. There is no requirement to register these TXT records with a unicast DNS service.
TXT Record Name | Corresponding Node API Resource |
---|---|
ver_slf | self |
ver_src | sources |
ver_flw | flows |
ver_dvc | devices |
ver_snd | senders |
ver_rcv | receivers |
The value of each of the above should be an unsigned 8-bit integer initialised to '0'. This integer MUST be incremented and mDNS TXT record updated whenever a change is made to the corresponding HTTP API resource on the Node. The integer must wrap back to a value of '0' after reaching a maximum value of '255' (MAX_UINT8_T).
For example, the 'ver_src' TXT record must be created when the Node first advertises itself via mDNS. If the data held within the HTTP resource for /sources is added to, removed from or edited, then the 'ver_src' text record must be modified (value incremented).
Versioning
A Node 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. See the [APIs](../docs/2.0. APIs.md) and [Upgrade Path](../docs/6.0. Upgrade Path.md) documentation for more details.
Receiver Subscriptions
This method is deprecated, but should be supported alongside any other connection mechanisms until it is removed in v2.0. Please see the NMOS Connection API specification for the current methods for creating connections between Senders and Receivers.
A PUT request to /receivers/{receiverId}/target will modify which Sender a Receiver is subscribed to.
In order to 'subscribe' a Receiver to a Sender, a PUT request should be made to this resource containing a full Sender object. In order to 'unsubscribe' a Receiver from a Sender, an empty object '{}' should be used in this PUT request. In both cases the target resource should respond with a 202 code (accepted) on success, and a response body matching the request body.
The Receiver's subscription object contains a 'sender_id' attribute which must be updated once a Receiver has successfully requested, parsed and actioned a change to the manifest_href is it connected to.
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 Node API base resource",
"title": "Node API base resource",
"items": {
"type": "string",
"enum": [
"self/",
"sources/",
"flows/",
"devices/",
"senders/",
"receivers/"
],
"minItems": 6,
"maxItems": 6,
"uniqueItems": true
}
}
Example:
[
"self/",
"sources/",
"flows/",
"devices/",
"senders/",
"receivers/"
]
Self
Get information about this Node
get /self
Get information about this Node
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the Node and the services which run on it",
"title": "Node resource",
"allOf": [
{ "$ref": "resource_core.json" },
{
"type": "object",
"required": [
"href",
"caps",
"api",
"services",
"clocks",
"interfaces"
],
"properties": {
"href": {
"description": "HTTP access href for the Node's API (deprecated)",
"type": "string",
"format": "uri"
},
"hostname": {
"description": "Node hostname (optional, deprecated)",
"type": "string",
"format": "hostname"
},
"api": {
"description": "URL fragments required to connect to the Node API",
"type": "object",
"required": ["versions", "endpoints"],
"properties": {
"versions": {
"description": "Supported API versions running on this Node",
"type": "array",
"items": {
"type": "string",
"pattern": "^v[0-9]+\\.[0-9]+$"
}
},
"endpoints": {
"description": "Host, port and protocol details required to connect to the API",
"type": "array",
"items": {
"type": "object",
"required": ["host", "port", "protocol"],
"properties": {
"host": {
"type": "string",
"description": "IP address or hostname which the Node API is running on",
"anyOf": [
{"format": "hostname"},
{"format": "ipv4"},
{"format": "ipv6"}
]
},
"port": {
"type": "integer",
"description": "Port number which the Node API is running on",
"minimum": 1,
"maximum": 65535
},
"protocol": {
"type": "string",
"description": "Protocol supported by this instance of the Node API",
"enum": ["http", "https"]
}
}
}
}
}
},
"caps": {
"description": "Capabilities (not yet defined)",
"type": "object"
},
"services": {
"description": "Array of objects containing a URN format type and href",
"type": "array",
"items": {
"type": "object",
"required": ["href", "type"],
"properties": {
"href": {
"type": "string",
"description": "URL to reach a service running on the Node",
"format": "uri"
},
"type": {
"type": "string",
"description": "URN identifying the type of service",
"format": "uri"
}
}
}
},
"clocks": {
"description": "Clocks made available to Devices owned by this Node",
"type": "array",
"items": {
"anyOf": [
{ "$ref": "clock_internal.json" },
{ "$ref": "clock_ptp.json" }
]
}
},
"interfaces": {
"description":"Network interfaces made available to devices owned by this Node. Port IDs and Chassis IDs are used to inform topology discovery via IS-06, and require that interfaces implement ARP at a minimum, and ideally LLDP.",
"type": "array",
"items": {
"type": "object",
"required": ["chassis_id", "port_id", "name"],
"properties": {
"chassis_id": {
"description": "Chassis ID of the interface, as signalled in LLDP from this node. Set to null where LLDP is unsuitable for use (ie. virtualised environments)",
"anyOf": [
{
"type": "string",
"pattern": "^([0-9a-f]{2}-){5}([0-9a-f]{2})$",
"description": "When the Chassis ID is a MAC address, use this format"
},
{
"type": "string",
"pattern": "^.+$",
"description": "When the Chassis ID is anything other than a MAC address, a freeform string may be used"
},
{
"type": "null",
"description": "When the Chassis ID is unavailable it should be set to null"
}
]
},
"port_id": {
"description": "Port ID of the interface, as signalled in LLDP or via ARP responses from this node. Must be a MAC address",
"type": "string",
"pattern": "^([0-9a-f]{2}-){5}([0-9a-f]{2})$"
},
"name": {
"description": "Name of the interface (unique in scope of this node). This attribute is used by sub-resources of this node such as senders and receivers to refer to interfaces to which they are bound.",
"type": "string"
}
}
}
}
}
}
]
}
Example:
{
"version": "1441700172:318426300",
"hostname": "host1",
"caps": {},
"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"
}
],
"label": "host1",
"description": "host1",
"tags": {},
"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":"74-26-96-db-87-31",
"port_id":"74-26-96-db-87-31"
},
{
"name":"eth1",
"chassis_id":"74-26-96-db-87-31",
"port_id":"74-26-96-db-87-32"
}
]
}
Sources
List Sources
get /sources
List Sources
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Source resources",
"title": "Collection of Sources",
"items": {
"$ref": "source.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "Capture Card Source Video",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:video",
"caps": {},
"version": "1441703336:902850419",
"parents": [],
"label": "CaptureCardSourceVideo",
"id": "4569cea2-ab63-4f97-8dd1-bad4669ea5e4",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk0"
},
{
"description": "Capture Card Source Audio",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:audio",
"caps": {},
"version": "1441703336:912670314",
"parents": [],
"label": "CaptureCardSourceAudio",
"id": "fc97ab0f-b51b-4129-9385-dcaf30f9482b",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk0",
"channels": [
{
"label": "Left Channel",
"symbol": "L"
},
{
"label": "Right Channel",
"symbol": "R"
}
]
},
{
"description": "Capture Card Source Audio",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:audio",
"caps": {},
"version": "1441704614:174935325",
"parents": [],
"label": "CaptureCardSourceAudio",
"id": "9738780e-141f-4e19-8601-a157dc855aa2",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk0",
"channels": [
{
"label": "Left Channel",
"symbol": "L"
},
{
"label": "Right Channel",
"symbol": "R"
}
]
},
{
"description": "Capture Card Source Video",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:video",
"caps": {},
"version": "1441704614:163285887",
"parents": [],
"label": "CaptureCardSourceVideo",
"id": "02c46999-d532-4c52-905f-2e368a2af6cb",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk0"
},
{
"description": "Capture Card Source VANC",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:data",
"caps": {},
"version": "1453880605:374934072",
"parents": [],
"label": "Capture Card Source VANC",
"id": "0e635152-e501-4d4e-bb87-9f3fe05eb79a",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk0"
},
{
"description": "Capture Card Source TR-04/2022-6",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:mux",
"caps": {},
"version": "1453880605:374934072",
"parents": [],
"label": "Capture Card Source TR-04/2022-6",
"id": "782fac41-17f6-4a21-8186-57ba63a1a8d3",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk0"
},
{
"description": "Capture Card Source 2022-6 (No Refclock)",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:mux",
"caps": {},
"version": "1453880605:374934072",
"parents": [],
"label": "Capture Card Source 2022-6 (No Refclock)",
"id": "3ca37fce-c0cf-42a6-86ad-43635a53b5bb",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": null
}
]
Get a single Source
get /sources/{sourceId}
Get a single Source
URI Parameters
- sourceId: 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: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes a Source",
"title": "Source resource",
"oneOf": [
{ "$ref": "source_generic.json" },
{ "$ref": "source_audio.json" }
]
}
Example:
{
"description": "Capture Card Source Video",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:video",
"caps": {},
"version": "1441703336:902850419",
"parents": [],
"label": "CaptureCardSourceVideo",
"id": "4569cea2-ab63-4f97-8dd1-bad4669ea5e4",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk1"
}
HTTP status code 404
Returned when the requested Source ID 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"]
}
}
}
Flows
List Flows
get /flows
List Flows
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Flow resources",
"title": "Collection of Flows",
"items": {
"$ref": "flow.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "Test Card",
"tags": {},
"format": "urn:x-nmos:format:video",
"label": "Test Card",
"version": "1441704616:587121295",
"parents": [],
"source_id": "02c46999-d532-4c52-905f-2e368a2af6cb",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed",
"media_type": "video/raw",
"frame_width": 1920,
"frame_height": 1080,
"interlace_mode": "interlaced_tff",
"colorspace": "BT709",
"components": [
{
"name": "Y",
"width": 1920,
"height": 1080,
"bit_depth": 10
},
{
"name": "Cb",
"width": 960,
"height": 1080,
"bit_depth": 10
},
{
"name": "Cr",
"width": 960,
"height": 1080,
"bit_depth": 10
}
]
},
{
"description": "VANC Data",
"tags": {},
"format": "urn:x-nmos:format:data",
"label": "VANC Data",
"version": "1453880607:123995943",
"parents": [],
"source_id": "0e635152-e501-4d4e-bb87-9f3fe05eb79a",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"id": "db3bd465-2772-484f-8fac-830b0471258b",
"media_type": "video/smpte291"
},
{
"description": "TR-04 Video",
"tags": {},
"format": "urn:x-nmos:format:mux",
"label": "TR-04 Video",
"version": "1453880607:123995943",
"parents": [],
"source_id": "782fac41-17f6-4a21-8186-57ba63a1a8d3",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"id": "4857f747-96cf-4ed7-8f4b-9497199f1f25",
"media_type": "video/SMPTE2022-6"
}
]
Get a single Flow
get /flows/{flowId}
Get a single Flow
URI Parameters
- flowId: 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: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes a Flow",
"title": "Flow resource",
"anyOf": [
{ "$ref": "flow_video_raw.json" },
{ "$ref": "flow_video_coded.json" },
{ "$ref": "flow_audio_raw.json" },
{ "$ref": "flow_audio_coded.json" },
{ "$ref": "flow_data.json" },
{ "$ref": "flow_sdianc_data.json" },
{ "$ref": "flow_mux.json" }
]
}
Example:
{
"description": "Test Card",
"tags": {},
"format": "urn:x-nmos:format:video",
"label": "Test Card",
"version": "1441704616:587121295",
"parents": [],
"source_id": "02c46999-d532-4c52-905f-2e368a2af6cb",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed",
"media_type": "video/raw",
"frame_width": 1920,
"frame_height": 1080,
"interlace_mode": "interlaced_tff",
"colorspace": "BT709",
"components": [
{
"name": "Y",
"width": 1920,
"height": 1080,
"bit_depth": 10
},
{
"name": "Cb",
"width": 960,
"height": 1080,
"bit_depth": 10
},
{
"name": "Cr",
"width": 960,
"height": 1080,
"bit_depth": 10
}
]
}
HTTP status code 404
Returned when the requested Flow ID 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"]
}
}
}
Devices
List Devices
get /devices
List Devices
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Device resources",
"title": "Collection of Devices",
"items": {
"$ref": "device.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"receivers": [],
"label": "pipeline 3 default device",
"description": "pipeline 3 default device",
"tags": {},
"version": "1441704616:592733242",
"id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"type": "urn:x-nmos:device:pipeline",
"senders": [
"d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e"
],
"node_id": "3b8be755-08ff-452b-b217-c9151eb21193",
"controls": [
{
"type": "urn:x-manufacturer:control:generic",
"href": "wss://154.67.63.2:4535"
}
]
},
{
"receivers": [],
"label": "pipeline 1 default device",
"description": "pipeline 1 default device",
"tags": {},
"version": "1441703338:962976113",
"id": "67c25159-ce25-4000-a66c-f31fff890265",
"type": "urn:x-nmos:device:pipeline",
"senders": [],
"node_id": "3b8be755-08ff-452b-b217-c9151eb21193",
"controls": [
{
"type": "urn:x-manufacturer:control:generic",
"href": "ws://182.54.54.75:223"
},
{
"type": "urn:x-manufacturer:control:generic",
"href": "http://134.24.64.22/x-manufacturer/control/"
},
{
"type": "urn:x-manufacturer:control:legacy",
"href": "telnet://120.43.64.3:8080"
}
]
},
{
"receivers": [
"1eb53d65-ac83-441c-86f6-9b27df30ef0c"
],
"label": "pipeline 2 default device",
"description": "pipeline 2 default device",
"tags": {},
"version": "1441704514:993221361",
"id": "05017e08-b329-45f9-a566-a3f99cc11e4d",
"type": "urn:x-nmos:device:pipeline",
"senders": [],
"node_id": "3b8be755-08ff-452b-b217-c9151eb21193",
"controls": []
}
]
Get a single Device
get /devices/{deviceId}
Get a single Device
URI Parameters
- deviceId: 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: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes a Device",
"title": "Device resource",
"allOf": [
{ "$ref": "resource_core.json" },
{
"type": "object",
"required": [
"type",
"node_id",
"senders",
"receivers",
"controls"
],
"properties": {
"type": {
"description": "Device type URN",
"type": "string",
"oneOf": [
{
"enum": [
"urn:x-nmos:device:generic",
"urn:x-nmos:device:pipeline"
]
},
{
"not": {
"pattern": "^urn:x-nmos:"
}
}
],
"format": "uri"
},
"node_id": {
"description": "Globally unique identifier for the Node which initially created the Device. This attribute is used to ensure referential integrity by registry implementations.",
"type": "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}$"
},
"senders": {
"description": "UUIDs of Senders attached to the Device (deprecated)",
"type": "array",
"items": {
"type": "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}$"
}
},
"receivers": {
"description": "UUIDs of Receivers attached to the Device (deprecated)",
"type": "array",
"items": {
"type": "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}$"
}
},
"controls": {
"description": "Control endpoints exposed for the Device",
"type": "array",
"items": {
"type": "object",
"required": ["href", "type"],
"properties": {
"href": {
"type": "string",
"description": "URL to reach a control endpoint, whether http or otherwise",
"format": "uri"
},
"type": {
"type": "string",
"description": "URN identifying the control format",
"format": "uri"
}
}
}
}
}
}
]
}
Example:
{
"receivers": [],
"label": "pipeline 1 default device",
"description": "pipeline 1 default device",
"tags": {},
"version": "1441703338:962976113",
"id": "67c25159-ce25-4000-a66c-f31fff890265",
"type": "urn:x-nmos:device:pipeline",
"senders": [],
"node_id": "3b8be755-08ff-452b-b217-c9151eb21193",
"controls": [
{
"type": "urn:x-manufacturer:control:generic",
"href": "ws://182.54.54.75:223"
},
{
"type": "urn:x-manufacturer:control:generic",
"href": "http://134.24.64.22/x-manufacturer/control/"
},
{
"type": "urn:x-manufacturer:control:legacy",
"href": "telnet://120.43.64.3:8080"
}
]
}
HTTP status code 404
Returned when the requested Device ID 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"]
}
}
}
Senders
List Senders
get /senders
List Senders
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Sender resources",
"title": "Collection of Senders",
"items": {
"$ref": "sender.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "Test Card",
"label": "Test Card",
"version": "1441704616:890020555",
"manifest_href": "http://172.29.80.65/x-manufacturer/senders/d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e/stream.sdp",
"flow_id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed",
"id": "d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e",
"transport": "urn:x-nmos:transport:rtp.mcast",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"interface_bindings":[
"eth0",
"eth1"
],
"caps": {},
"tags": {},
"subscription": {
"receiver_id": null,
"active": true
}
}
]
Get a single Sender
get /senders/{senderId}
Get a single Sender
URI Parameters
- senderId: 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: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes a sender",
"title": "Sender resource",
"allOf": [
{ "$ref": "resource_core.json" },
{
"type": "object",
"required": [
"flow_id",
"transport",
"device_id",
"manifest_href",
"interface_bindings",
"subscription"
],
"properties": {
"caps": {
"description": "Capabilities of this sender",
"type": "object",
"properties":{
}
},
"flow_id": {
"description": "ID of the Flow currently passing via this Sender",
"type": ["string", "null"],
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"default": null
},
"transport": {
"description": "Transport type used by the Sender in URN format",
"type": "string",
"oneOf": [
{
"enum": [
"urn:x-nmos:transport:rtp",
"urn:x-nmos:transport:rtp.ucast",
"urn:x-nmos:transport:rtp.mcast",
"urn:x-nmos:transport:dash"
]
},
{
"not": {
"pattern": "^urn:x-nmos:"
}
}
],
"format": "uri"
},
"device_id": {
"description": "Device ID which this Sender forms part of. This attribute is used to ensure referential integrity by registry implementations.",
"type": "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}$"
},
"manifest_href": {
"description": "HTTP URL to a file describing how to connect to the Sender (SDP for RTP). The Sender's 'version' attribute should be updated if the contents of this file are modified. This URL may return an HTTP 404 where the 'active' parameter in the 'subscription' object is present and set to false (v1.2+ only).",
"type": "string",
"format": "uri"
},
"interface_bindings": {
"description": "Binding of Sender egress ports to interfaces on the parent Node. Should contain a single network interface unless a redundancy mechanism such as ST.2022-7 is in use, in which case each 'leg' should have its matching interface listed. Where the redundancy mechanism sends more than one copy of the stream via the same interface, that interface should be listed a corresponding number of times.",
"type": "array",
"items": {
"type":"string"
}
},
"subscription": {
"description": "Object containing the 'receiver_id' currently subscribed to (unicast only). Receiver_id should be null on initialisation, or when connected to a non-NMOS unicast Receiver.",
"type": "object",
"required": ["receiver_id", "active"],
"properties": {
"receiver_id": {
"type": ["string", "null"],
"description": "UUID of the Receiver that this Sender is currently subscribed to",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"default": null
},
"active": {
"type": "boolean",
"description": "Sender is enabled and configured to stream data to a single Receiver (unicast), or to the network via multicast or a pull-based mechanism",
"default": false
}
}
}
}
}
]
}
Example:
{
"description": "Test Card",
"label": "Test Card",
"version": "1441704616:890020555",
"manifest_href": "http://172.29.80.65/x-manufacturer/senders/d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e/stream.sdp",
"flow_id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed",
"id": "d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e",
"transport": "urn:x-nmos:transport:rtp.mcast",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"interface_bindings":[
"eth0",
"eth1"
],
"caps": {},
"tags": {},
"subscription": {
"receiver_id": null,
"active": true
}
}
HTTP status code 404
Returned when the requested Sender ID 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"]
}
}
}
Receivers
List Receivers
get /receivers
List Receivers
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Receiver resources",
"title": "Collection of Receivers",
"items": {
"$ref": "receiver.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "",
"format": "urn:x-nmos:format:video",
"tags": {},
"caps": {
"media_types": [
"video/raw"
]
},
"subscription": {
"sender_id": "2683ad14-642f-459d-a169-ef91c76cec6b",
"active": true
},
"version": "1441704532:450093308",
"label": "RTPRx",
"id": "1eb53d65-ac83-441c-86f6-9b27df30ef0c",
"transport": "urn:x-nmos:transport:rtp",
"interface_bindings":[
"eth0",
"eth1"
],
"device_id": "05017e08-b329-45f9-a566-a3f99cc11e4d"
}
]
Get a single Receiver
get /receivers/{receiverId}
Get a single Receiver
URI Parameters
- receiverId: 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: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes a Receiver",
"title": "Receiver resource",
"oneOf": [
{ "$ref": "receiver_video.json" },
{ "$ref": "receiver_audio.json" },
{ "$ref": "receiver_data.json" },
{ "$ref": "receiver_mux.json" }
]
}
Example:
{
"description": "",
"format": "urn:x-nmos:format:video",
"tags": {},
"caps": {
"media_types": [
"video/raw"
]
},
"subscription": {
"sender_id": "2683ad14-642f-459d-a169-ef91c76cec6b",
"active": true
},
"version": "1441704532:450093308",
"label": "RTPRx",
"id": "1eb53d65-ac83-441c-86f6-9b27df30ef0c",
"transport": "urn:x-nmos:transport:rtp",
"interface_bindings": [
"eth0",
"eth1"
],
"device_id": "05017e08-b329-45f9-a566-a3f99cc11e4d"
}
HTTP status code 404
Returned when the requested Receiver ID 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"]
}
}
}
Request a change to a Receiver's subscription (deprecated)
put /receivers/{receiverId}/target
Request a change to a Receiver's subscription (deprecated)
URI Parameters
- receiverId: 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
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the possible requests to a Node's Receiver target resource",
"title": "Receiver target resource",
"oneOf": [
{ "$ref": "sender.json" },
{
"type": "object",
"description": "Describes an empty object",
"title": "Empty object schema",
"additionalProperties": false,
"properties": {
}
}
]
}
Example:
{
"description": "Test Card",
"label": "Test Card",
"version": "1441704616:890020555",
"manifest_href": "http://172.29.80.65/x-manufacturer/senders/d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e/stream.sdp",
"flow_id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed",
"id": "d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e",
"transport": "urn:x-nmos:transport:rtp.mcast",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"interface_bindings":[
"eth0",
"eth1"
],
"caps": {},
"tags": {},
"subscription": {
"receiver_id": null,
"active": true
}
}
HTTP status code 202
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the possible requests to a Node's Receiver target resource",
"title": "Receiver target resource",
"oneOf": [
{ "$ref": "sender.json" },
{
"type": "object",
"description": "Describes an empty object",
"title": "Empty object schema",
"additionalProperties": false,
"properties": {
}
}
]
}
Example:
{
"description": "Test Card",
"label": "Test Card",
"version": "1441704616:890020555",
"manifest_href": "http://172.29.80.65/x-manufacturer/senders/d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e/stream.sdp",
"flow_id": "5fbec3b1-1b0f-417d-9059-8b94a47197ed",
"id": "d7aa5a30-681d-4e72-92fb-f0ba0f6f4c3e",
"transport": "urn:x-nmos:transport:rtp.mcast",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"interface_bindings":[
"eth0",
"eth1"
],
"caps": {},
"tags": {},
"subscription": {
"receiver_id": null,
"active": true
}
}
HTTP status code 400
Returned when the PUT 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"]
}
}
}
HTTP status code 404
Returned when the requested Receiver ID 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"]
}
}
}