Query API documentation version v1.3

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

  • version: required(v1.3)

Overview

The Query API is exposed by NMOS discovery Nodes. It is used to expose the contents of the (distributed) registry to all Nodes on the network. In smaller deployments where no such registry is available, Nodes with their own control capabilities fall back to interrogating Nodes directly using the peer-to-peer specification. This is a read-only API.

Attributes defined as 'Optional' in schemas MUST be returned by the Query API if they exist within the registry. The presence declaration relates more to whether it is required for them to be registered at the Registration API side, or presented via the Node API.

Further Documentation

Further normative documentation covering the behaviour of this API is contained in the docs folder of this repository.

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 Query API base resource",
  "title": "Query API base resource",
  "items": {
    "type": "string",
    "enum": [
      "nodes/",
      "sources/",
      "flows/",
      "devices/",
      "senders/",
      "receivers/",
      "subscriptions/"
    ]
  },
  "minItems": 7,
  "maxItems": 7,
  "uniqueItems": true
}

Example:

[
    "subscriptions/", 
    "flows/", 
    "sources/", 
    "nodes/", 
    "devices/", 
    "senders/", 
    "receivers/"
]

Nodes

get

get

List Nodes. NB: Query parameters should be implemented for all permitted resource attributes.

get

get

Get a single Node

Get a single Node

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

Query Parameters

  • query.downgrade: required(string - pattern: ^v[0-9]+.[0-9]+$)

    Minimum API version to return resources from if they exists within the registry

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"]
                  },
                  "authorization": {
                    "type": "boolean",
                    "description": "This endpoint requires authorization",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "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"
              },
              "authorization": {
                "type": "boolean",
                "description": "This endpoint requires authorization",
                "default": false
              }
            }
          }
        },
        "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"
              },
              "attached_network_device": {
                "type": "object",
                "required": ["chassis_id", "port_id"],
                "properties": {
                  "chassis_id": {
                    "description": "Chassis ID of the attached network device, as signalled in LLDP received by this Node.",
                    "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"
                      }
                    ]
                  },
                  "port_id": {
                    "description": "Port ID of the attached network device, as signalled in LLDP received by this Node.",
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^([0-9a-f]{2}-){5}([0-9a-f]{2})$",
                        "description": "When the Port ID is a MAC address, use this format"
                      },
                      {
                        "type": "string",
                        "pattern": "^.+$",
                        "description": "When the Port ID is anything other than a MAC address, a freeform string may be used"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}

Example:

{
    "version": "1441716120:318744030",
    "hostname": "host1",
    "label": "host1",
    "description": "host1",
    "tags": {},
    "href": "http://172.29.176.102:12345/",
    "api": {
        "versions": ["v1.1", "v1.2", "v1.3"],
        "endpoints": [
            {
                "host": "172.29.176.102",
                "port": 12345,
                "protocol": "http"
            }
        ]
    },
    "services": [
        {
            "href": "http://172.29.176.102:12345/x-manufacturer/status/",
            "type": "urn:x-manufacturer:service:status"
        },
        {
            "href": "http://172.29.176.102:12345/x-manufacturer/pipelinemanager/",
            "type": "urn:x-manufacturer:service:pipelinemanager"
        },
        {
            "href": "http://172.29.176.102:12345/x-manufacturer/mdnsbridge/",
            "type": "urn:x-manufacturer:service:mdnsbridge"
        }
    ],
    "caps": {},
    "id": "c8ba20e9-e197-4ec5-8764-4da672128589",
    "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"
      }
    ]
}

HTTP status code 400

The requested downgrade query moves between major API versions which is not permitted.

HTTP status code 404

Returned when the requested Node 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"]
    }
  }
}

HTTP status code 409

Returned when the requested Node ID exists in the registry at a lower API version and a query downgrade has not been requested, or the requested downgrade does not extend as far as the resource's API version. The correct API version is identified via the Location header.

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/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"]
    }
  }
}

HTTP status code 501

The query parameters specified are not currently supported by this implementation.

Sources

get

get

List Sources. NB: Query parameters should be implemented for all permitted resource attributes.

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

Query Parameters

  • query.downgrade: required(string - pattern: ^v[0-9]+.[0-9]+$)

    Minimum API version to return resources from if they exists within the registry

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" },
    { "$ref": "source_data.json" }
  ]
}

Example:

{
    "description": "Capture Card Source Video",
    "format": "urn:x-nmos:format:video",
    "tags": {
        "SourceDeviceType": [
            "HD Camera"
        ],
        "host": [
            "host1"
        ],
        "Location": [
            "Location 1"
        ]
    },
    "caps": {},
    "version": "1441722516:851371645",
    "parents": [],
    "label": "CaptureCardSourceVideo",
    "id": "c23c6a65-8e91-4f6c-a484-046363dbca29",
    "device_id": "65fa8c20-890e-4b86-87b2-cfd9df91b7f8",
    "clock_name": "clk1"
}

HTTP status code 400

The requested downgrade query moves between major API versions which is not permitted.

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

HTTP status code 409

Returned when the requested Source ID exists in the registry at a lower API version and a query downgrade has not been requested, or the requested downgrade does not extend as far as the resource's API version. The correct API version is identified via the Location header.

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/sources/c23c6a65-8e91-4f6c-a484-046363dbca29

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 501

The query parameters specified are not currently supported by this implementation.

Flows

get

get

List Flows. NB: Query parameters should be implemented for all permitted resource attributes.

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

Query Parameters

  • query.downgrade: required(string - pattern: ^v[0-9]+.[0-9]+$)

    Minimum API version to return resources from if they exists within the registry

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_json_data.json" },
    { "$ref": "flow_mux.json" }
  ]
}

Example:

{
    "description": "Capture Audio Proxy",
    "format": "urn:x-nmos:format:audio",
    "tags": {
        "host": [
            "host1"
        ]
    },
    "label": "Capture Audio Proxy",
    "version": "1441812152:154331951",
    "parents": [],
    "source_id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f",
    "device_id": "169feb2c-3fae-42a5-ae2e-f6f8cbce29cf",
    "id": "b3bb5be7-9fe9-4324-a5bb-4c70e1084449",
    "media_type": "audio/L16",
    "sample_rate": {
        "numerator": 48000
    },
    "bit_depth": 16
}

HTTP status code 400

The requested downgrade query moves between major API versions which is not permitted.

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

HTTP status code 409

Returned when the requested Flow ID exists in the registry at a lower API version and a query downgrade has not been requested, or the requested downgrade does not extend as far as the resource's API version. The correct API version is identified via the Location header.

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/flows/b3bb5be7-9fe9-4324-a5bb-4c70e1084449

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 501

The query parameters specified are not currently supported by this implementation.

Devices

get

get

List Devices. NB: Query parameters should be implemented for all permitted resource attributes.

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

Query Parameters

  • query.downgrade: required(string - pattern: ^v[0-9]+.[0-9]+$)

    Minimum API version to return resources from if they exists within the registry

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": [
            {
              "pattern": "^urn:x-nmos:device:"
            },
            {
              "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"
              },
              "authorization": {
                "type": "boolean",
                "description": "This endpoint requires authorization",
                "default": false
              }
            }
          }
        }
      }
    }
  ]
}

Example:

{
    "receivers": [
        "863532de-a97d-4597-989a-e79688f2d5f9",
        "632d7e6d-7357-44de-a425-a94fbe94974e",
        "95ef711b-564d-4655-a98b-5b9ccfb419d7",
        "9ee74607-f831-42f5-af08-a614ce0706df",
        "1311bf13-869c-45b4-915e-8b4e8b8e26fd",
        "debcd758-129d-4e0b-a0e3-f1d9ce5edfbc",
        "0fee9741-e266-4c27-b480-1f897463ea4b",
        "ef9e58bd-431a-466d-a67f-0318858b981c",
        "68ca0867-ec4b-4eca-92e0-4c4c668a72b0"
    ],
    "label": "pipeline 1 default device",
    "description": "pipeline 1 default device",
    "tags": {},
    "version": "1441723676:366608283",
    "senders": [],
    "id": "a370d258-69de-4422-860a-ee4cf32ee9f4",
    "node_id": "3a25a674-e6eb-4987-84ad-ef479fe4d527",
    "type": "urn:x-nmos:device:pipeline",
    "controls": [
        {
            "type": "urn:x-manufacturer:control:generic",
            "href": "wss://154.67.62.2:4635",
            "authorization": false
        }
    ]
}

HTTP status code 400

The requested downgrade query moves between major API versions which is not permitted.

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

HTTP status code 409

Returned when the requested Device ID exists in the registry at a lower API version and a query downgrade has not been requested, or the requested downgrade does not extend as far as the resource's API version. The correct API version is identified via the Location header.

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/devices/a370d258-69de-4422-860a-ee4cf32ee9f4

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 501

The query parameters specified are not currently supported by this implementation.

Senders

get

get

List Senders. NB: Query parameters should be implemented for all permitted resource attributes.

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

Query Parameters

  • query.downgrade: required(string - pattern: ^v[0-9]+.[0-9]+$)

    Minimum API version to return resources from if they exists within the registry

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. Set to null when a Flow is not currently internally routed to the 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": [
            {
              "pattern": "^urn:x-nmos:transport:"
            },
            {
              "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(S) accessible URL to a file describing how to connect to the Sender. Set to null when the transport type used by the Sender does not require a transport file.",
          "type": ["string", "null"],
          "format": "uri"
        },
        "interface_bindings": {
          "description": "Binding of Sender egress ports to interfaces on the parent Node.",
          "type": "array",
          "items": {
            "type":"string"
          }
        },
        "subscription": {
          "description": "Object indicating how this Sender is currently configured to send data.",
          "type": "object",
          "required": ["receiver_id", "active"],
          "properties": {
            "receiver_id": {
              "type": ["string", "null"],
              "description": "UUID of the Receiver to which this Sender is currently configured to send data. Only set if it is active, uses a unicast push-based transport and is sending to an NMOS Receiver; otherwise 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
            },
            "active": {
              "type": "boolean",
              "description": "Sender is enabled and configured to send data",
              "default": false
            }
          }
        }
      }
    }
  ]
}

Example:

{
    "description": "Camera 1",
    "label": "Camera 1",
    "manifest_href": "http://172.29.176.146/x-manufacturer/senders/171d5c80-7fff-4c23-9383-46503eb1c63e/stream.sdp",
    "version": "1441723958:235623703",
    "flow_id": "b25d445a-20dc-4937-a8a1-5cb3d5c613ee",
    "id": "171d5c80-7fff-4c23-9383-46503eb1c63e",
    "transport": "urn:x-nmos:transport:rtp.mcast",
    "interface_bindings":[
      "eth0",
      "eth1"
    ],
    "device_id": "c501ae64-f525-48b7-9816-c5e8931bc017",
    "caps": {},
    "tags": {},
    "subscription": {
      "receiver_id": null,
      "active": true
    }
}

HTTP status code 400

The requested downgrade query moves between major API versions which is not permitted.

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

HTTP status code 409

Returned when the requested Sender ID exists in the registry at a lower API version and a query downgrade has not been requested, or the requested downgrade does not extend as far as the resource's API version. The correct API version is identified via the Location header.

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/senders/171d5c80-7fff-4c23-9383-46503eb1c63e

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 501

The query parameters specified are not currently supported by this implementation.

Receivers

get

get

List Receivers. NB: Query parameters should be implemented for all permitted resource attributes.

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

Query Parameters

  • query.downgrade: required(string - pattern: ^v[0-9]+.[0-9]+$)

    Minimum API version to return resources from if they exists within the registry

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": "RTP Receiver",
    "tags": {
        "Location": [
            "Location 1"
        ]
    },
    "format": "urn:x-nmos:format:video",
    "caps": {
        "media_types": [
            "video/raw"
        ]
    },
    "device_id": "0d0cb97e-b96a-4a39-887f-d491492d9081",
    "version": "1441895693:480000000",
    "label": "Viewer",
    "id": "3350d113-1593-4271-a7f5-f4974415bb8e",
    "transport": "urn:x-nmos:transport:rtp",
    "interface_bindings":[
      "eth1"
    ],
    "subscription": {
        "sender_id": "55311762-8003-48fa-a645-0a0c7621ce45",
        "active": true
    }
}

HTTP status code 400

The requested downgrade query moves between major API versions which is not permitted.

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

HTTP status code 409

Returned when the requested Receiver ID exists in the registry at a lower API version and a query downgrade has not been requested, or the requested downgrade does not extend as far as the resource's API version. The correct API version is identified via the Location header.

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/receivers/3350d113-1593-4271-a7f5-f4974415bb8e

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 501

The query parameters specified are not currently supported by this implementation.

Subscriptions

options post get

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

post

Create a WebSocket subscription to an API resource

get

List available WebSocket connections providing real-time updates on resource changes (for debug use only)

Create a WebSocket subscription to an API resource

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Create a new subscription to a Query API",
  "title": "Subscription creation",
  "required": [
    "max_update_rate_ms",
    "persist",
    "resource_path",
    "params"
  ],
  "properties": {
    "max_update_rate_ms": {
      "description": "Rate limiting for messages. Sets the minimum interval (in milliseconds) between consecutive WebSocket messages.",
      "type": "integer",
      "default": 100
    },
    "persist": {
      "description": "Whether the API will retain or destroy the subscription after the final client disconnects",
      "type": "boolean",
      "default": false
    },
    "secure": {
      "description": "Whether a secure WebSocket connection (wss://) is required. NB: Default should be 'true' if the API is being presented via HTTPS, and 'false' otherwise.",
      "type": "boolean"
    },
    "resource_path": {
      "description": "HTTP resource path in the Query API to which this subscription relates",
      "type": "string",
      "enum": ["/nodes", "/devices", "/sources", "/flows", "/senders", "/receivers"]
    },
    "params": {
      "description": "Object containing attributes to filter the resource on as per the Query Parameters specification. Can be empty.",
      "type": "object"
    },
    "authorization": {
      "type": "boolean",
      "description": "Whether the WebSocket connection requires authorization. NB: Default should be 'true' if the API requires authorization, and 'false' otherwise."
    }
  }
}

Example:

{
    "max_update_rate_ms": 100,
    "resource_path": "/nodes",
    "params": {
        "label": "host1"
    },
    "persist": false,
    "secure": false
}

HTTP status code 200

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/subscriptions/7c903667-7113-4a8f-8865-1c63f9070a9e

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A single subscription to a Query API",
  "title": "Subscription",
  "required": [
    "id",
    "ws_href",
    "max_update_rate_ms",
    "persist",
    "secure",
    "resource_path",
    "params"
  ],
  "properties": {
    "id": {
      "description": "Globally unique identifier for the subscription",
      "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}$"
    },
    "ws_href": {
      "description": "Address to connect to for the WebSocket subscription",
      "type": "string",
      "format": "uri"
    },
    "max_update_rate_ms": {
      "description": "Rate limiting for messages. Sets the minimum interval (in milliseconds) between consecutive WebSocket messages.",
      "type": "integer",
      "default": 100
    },
    "persist": {
      "description": "Whether the API will retain or destroy the subscription after the final client disconnects",
      "type": "boolean",
      "default": false
    },
    "secure": {
      "description": "Whether a secure WebSocket connection (wss://) is required.",
      "type": "boolean"
    },
    "resource_path": {
      "description": "HTTP resource path in the Query API to which this subscription relates",
      "type": "string",
      "enum": ["/nodes", "/devices", "/sources", "/flows", "/senders", "/receivers"]
    },
    "params": {
      "description": "Object containing attributes to filter the resource on as per the Query Parameters specification. Can be empty.",
      "type": "object"
    },
    "authorization": {
      "type": "boolean",
      "description": "Whether the WebSocket connection requires authorization."
    }
  }
}

Example:

{
    "max_update_rate_ms": 100,
    "resource_path": "/nodes",
    "params": {
        "label": "host1"
    },
    "persist": false,
    "secure": false,
    "authorization": false,
    "ws_href": "ws://172.29.80.52:8870/ws/?uid=7c903667-7113-4a8f-8865-1c63f9070a9e",
    "id": "7c903667-7113-4a8f-8865-1c63f9070a9e"
}

HTTP status code 201

Headers

  • Location: required(string)

    Example:

    /x-nmos/query/{version}/subscriptions/7c903667-7113-4a8f-8865-1c63f9070a9e

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A single subscription to a Query API",
  "title": "Subscription",
  "required": [
    "id",
    "ws_href",
    "max_update_rate_ms",
    "persist",
    "secure",
    "resource_path",
    "params"
  ],
  "properties": {
    "id": {
      "description": "Globally unique identifier for the subscription",
      "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}$"
    },
    "ws_href": {
      "description": "Address to connect to for the WebSocket subscription",
      "type": "string",
      "format": "uri"
    },
    "max_update_rate_ms": {
      "description": "Rate limiting for messages. Sets the minimum interval (in milliseconds) between consecutive WebSocket messages.",
      "type": "integer",
      "default": 100
    },
    "persist": {
      "description": "Whether the API will retain or destroy the subscription after the final client disconnects",
      "type": "boolean",
      "default": false
    },
    "secure": {
      "description": "Whether a secure WebSocket connection (wss://) is required.",
      "type": "boolean"
    },
    "resource_path": {
      "description": "HTTP resource path in the Query API to which this subscription relates",
      "type": "string",
      "enum": ["/nodes", "/devices", "/sources", "/flows", "/senders", "/receivers"]
    },
    "params": {
      "description": "Object containing attributes to filter the resource on as per the Query Parameters specification. Can be empty.",
      "type": "object"
    },
    "authorization": {
      "type": "boolean",
      "description": "Whether the WebSocket connection requires authorization."
    }
  }
}

Example:

{
    "max_update_rate_ms": 100,
    "resource_path": "/nodes",
    "params": {
        "label": "host1"
    },
    "persist": false,
    "secure": false,
    "authorization": false,
    "ws_href": "ws://172.29.80.52:8870/ws/?uid=7c903667-7113-4a8f-8865-1c63f9070a9e",
    "id": "7c903667-7113-4a8f-8865-1c63f9070a9e"
}

HTTP status code 400

Returned when the POST request is incorrectly formatted, missing mandatory attributes or an attribute is invalid given the API's configuration

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 501

The query parameters specified are not currently supported by this implementation.

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 options delete

get

Get a single subscription (for debug use only)

options

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

delete

Delete a single subscription

Get a single subscription (for debug use only)

URI Parameters

  • subscriptionId: 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": "A single subscription to a Query API",
  "title": "Subscription",
  "required": [
    "id",
    "ws_href",
    "max_update_rate_ms",
    "persist",
    "secure",
    "resource_path",
    "params"
  ],
  "properties": {
    "id": {
      "description": "Globally unique identifier for the subscription",
      "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}$"
    },
    "ws_href": {
      "description": "Address to connect to for the WebSocket subscription",
      "type": "string",
      "format": "uri"
    },
    "max_update_rate_ms": {
      "description": "Rate limiting for messages. Sets the minimum interval (in milliseconds) between consecutive WebSocket messages.",
      "type": "integer",
      "default": 100
    },
    "persist": {
      "description": "Whether the API will retain or destroy the subscription after the final client disconnects",
      "type": "boolean",
      "default": false
    },
    "secure": {
      "description": "Whether a secure WebSocket connection (wss://) is required.",
      "type": "boolean"
    },
    "resource_path": {
      "description": "HTTP resource path in the Query API to which this subscription relates",
      "type": "string",
      "enum": ["/nodes", "/devices", "/sources", "/flows", "/senders", "/receivers"]
    },
    "params": {
      "description": "Object containing attributes to filter the resource on as per the Query Parameters specification. Can be empty.",
      "type": "object"
    },
    "authorization": {
      "type": "boolean",
      "description": "Whether the WebSocket connection requires authorization."
    }
  }
}

Example:

{
    "max_update_rate_ms": 100,
    "resource_path": "/nodes",
    "params": {},
    "persist": false,
    "secure": false,
    "authorization": false,
    "ws_href": "ws://172.29.80.52:8870/ws/?uid=7c903667-7113-4a8f-8865-1c63f9070a9e",
    "id": "7c903667-7113-4a8f-8865-1c63f9070a9e"
}

HTTP status code 404

Returned when the requested Subscription 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"]
    }
  }
}

HTTP status code 409

Returned when the requested Subscription ID 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/query/{version}/subscriptions/7c903667-7113-4a8f-8865-1c63f9070a9e

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

A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes

URI Parameters

  • subscriptionId: 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

HTTP status code 403

Delete a single subscription

URI Parameters

  • subscriptionId: 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 403

Returned when a DELETE request is made against a non-persistent subscription which is managed by the Query API and cannot be deleted

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

HTTP status code 409

Returned when the requested Subscription ID 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/query/{version}/subscriptions/7c903667-7113-4a8f-8865-1c63f9070a9e

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