Query API documentation version v1.1

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

  • version: required(v1.1)

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' 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.

DNS-SD Advertisement

Query APIs MUST produce an mDNS advertisement of the type _nmos-query._tcp. This MAY be accompanied by a unicast DNS announcement of the same type.

The IP address and port of the Query 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' dependent on the protocol in use by the Query 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.

pri

The DNS-SD advertisement MUST include a TXT record with key 'pri' and an integer value. Servers MAY additionally represent a matching priority via the DNS-SD SRV record 'priority' and 'weight' as defined in RFC 2782. The TXT record should be used in favour to the SRV priority and weight where these values differ in order to overcome issues in the Bonjour and Avahi implementations. Values 0 to 99 correspond to an active NMOS Query API (zero being the highest priority). Values 100+ are reserved for development work to avoid colliding with a live system.

Websockets

Persistent connections to the Query API are supported via Websockets which can be set up via the /subscriptions resource. Query APIs may additionally support the HTTP 'Upgrade' header sent by clients to upgrade an HTTP GET request to a Websocket. In cases where this is performed, a corresponding entry in /subscriptions must also be created with matching query parameters.

Versioning

A Query 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.

Query Parameters

As a Query API may provide access to many thousands of resources, query parameters provide the means to narrow down these results. Any attribute which may be returned by a particular API resource SHOULD be available to use as a query parameter, however this RAML documentation only explicitly identifies core attributes under 'queryParameters'.

For a full description of the expected querying behaviour along with examples, please see the [Query Parameters Documentation](../docs/2.5. APIs - Query Parameters.md).

Basic Queries and Downgrade Queries SHOULD be supported. Advanced queries using RQL, ancestry tracking and similar MAY be supported.

** Basic Queries **

Basic queries make use of standard HTTP GET query parameters in the form '?key=value'. Keys may match any attribute which the API schemas indicate could be returned by a given resource.

  • Querying Within Objects

Querying using attributes of objects is permitted via the use of a '.' separator. For example, the /receivers resource may be queried with '?subscription.sender_id=2683ad14-642f-459d-a169-ef91c76cec6b'.

  • Querying Within Arrays

Querying using attributes of objects held within arrays is permitted via the use of a '.' separator. For example, the /nodes resource may be queried with '?services.type=urn:x-manufacturer:service:tally'. More advanced queries within arrays may require use of the Resource Query Language 'in()' operator.

** Downgrade Queries **

In order to streamline upgrades from one API version to another a Query API may sit in front of a registry which holds registered data matching multiple API versions' schemas. By default the Query API must only return data matching the API version specified in the request URL, however the client may choose to request mixed versions of data if it is capable of handling the potential missing keys.

Downgrades MUST only be performed between minor API versions as major versions may remove or re-purpose attributes. Clients which support multiple major API versions should retrieve this data via multiple HTTP requests or websocket subscriptions.

** Resource Query Language **

Given the constraints of using a standard '?variable=value&variable2=value2' query syntax, Query APIs MAY support Resource Query Language (https://github.com/persvr/rql/) in order to support more advanced queries.

RQL should be formatted in the normalised form as opposed to using FIQL syntax, and passed via the query string using '?query.rql=...'.

Querying within objects and arrays should be performed as in the Basic Queries case by using the '.' separator.

When an RQL query is specified, the Basic Queries format MAY be ignored in order to simplify implementation.

Note that as RQL permits the definition of very complex queries, the server may return a 400 error code to indicate that it is refusing to action the client's request due to the query's complexity.

  • Constraints

Not all RQL operators will be suitable for use with a Query API. It is suggested that the following operators are supported, however these are not mandated and implementations may choose to support their own subset.

  1. Functions: in(), out(), sort(), like(), select()

  2. Logical Operators: and(), or(), not()

  3. Relational Operators: eq(), ne(), gt(), ge(), lt(), le()

NB: It is suggested that limit() is not implemented as paging and associated limits is specified directly by the Query API.

** Querying Ancestry **

Sources and Flows list their 'parents' in an array. A Query API implementing ancestry tracking may be queried using '?query.ancestry_...' parameters in order to identify parents or children of a given Source or Flow.

Base

get

get

List of paths available from this API

List of paths available from this API

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

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

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

Example:

{
    "version": "1441716120:318744030",
    "hostname": "host1",
    "label": "host1",
    "description": "host1",
    "tags": {},
    "href": "http://172.29.176.102:12345/",
    "api": {
        "versions": ["v1.1"],
        "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
        }
    ]
}

HTTP status code 404

Returned when the requested Node ID does not exist

Body

Media type: application/json

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

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/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 404

Returned when the requested Source ID does not exist

Body

Media type: application/json

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

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/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 404

Returned when the requested Flow ID does not exist

Body

Media type: application/json

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

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

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

HTTP status code 404

Returned when the requested Device ID does not exist

Body

Media type: application/json

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

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

Example:

{
    "description": "Camera 1", 
    "label": "Camera 1", 
    "manifest_href": "http://172.29.176.146:12345/x-nmos/node/v1.1/self/pipelinemanager/run/pipeline/1/pipel/ipp_rtptxdfb1/misc/sdp/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", 
    "device_id": "c501ae64-f525-48b7-9816-c5e8931bc017",
    "tags": {}
}

HTTP status code 404

Returned when the requested Sender ID does not exist

Body

Media type: application/json

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

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/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", 
    "subscription": {
        "sender_id": "55311762-8003-48fa-a645-0a0c7621ce45"
    }
}

HTTP status code 404

Returned when the requested Receiver ID does not exist

Body

Media type: application/json

Subscriptions

post get

post

Create a websocket subscription to an API resource

get

List active connections to websockets providing real-time updates on resource changes

Create a websocket subscription to an API resource

Body

Media type: application/json

Example:

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

HTTP status code 200

Body

Media type: application/json

Example:

{
    "max_update_rate_ms": 100,
    "resource_path": "/nodes",
    "params": {
        "label": "host1"
    },
    "persist": false,
    "secure": 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

Body

Media type: application/json

Example:

{
    "max_update_rate_ms": 100,
    "resource_path": "/nodes",
    "params": {
        "label": "host1"
    },
    "persist": false,
    "secure": 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 or missing mandatory attributes

Body

Media type: application/json

get delete

get

Get a single subscription

delete

Delete a single subscription

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

Body

Media type: application/json

HTTP status code 200

Body

Media type: application/json

Example:

{
    "max_update_rate_ms": 100,
    "resource_path": "/nodes",
    "params": {},
    "persist": false,
    "secure": 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

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

Body

Media type: application/json

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

HTTP status code 404

Returned when the requested Subscription ID does not exist

Body

Media type: application/json