Node API documentation version v1.1

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

  • version: required(v1.1)

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.

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 NameCorresponding Node API Resource
ver_slfself
ver_srcsources
ver_flwflows
ver_dvcdevices
ver_sndsenders
ver_rcvreceivers

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

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

get

get

List of paths available from this API

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

get

Get information about this Node

Sources

get

get

List Sources

get

get

Get a single Source

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

get

get

List Flows

get

get

Get a single Flow

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

get

get

List Devices

get

get

Get a single Device

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",
          "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",
          "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",
          "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

get

get

List Senders

get

get

Get a single Sender

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"
      ],
      "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",
          "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)",
          "type": "string",
          "format": "uri"
        }
      }
    }
  ]
}

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",
    "tags": {}
}

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

get

get

List Receivers

get

get

Get a single Receiver

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"
    },
    "version": "1441704532:450093308",
    "label": "RTPRx",
    "id": "1eb53d65-ac83-441c-86f6-9b27df30ef0c",
    "transport": "urn:x-nmos:transport:rtp",
    "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"]
    }
  }
}

put

put

Request a change to a Receiver's subscription

Request a change to a Receiver's subscription

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:

{
  "$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,
      "required": [
      ],
      "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",
    "tags": {}
}

HTTP status code 202

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"
      ],
      "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",
          "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)",
          "type": "string",
          "format": "uri"
        }
      }
    }
  ]
}

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",
    "tags": {}
}

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"]
    }
  }
}