Query API documentation version v1.0

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

  • version: required(v1.0)

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.

mDNS Advertisement

Query APIs MUST produce an mDNS advertisement of the type _nmos-query._tcp

The mDNS advertisement MUST include a TXT record with key 'pri' and an integer value. 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. NB: In future versions of the specification it is likely that the 'priority' and 'weight' as specified by RFC 2782 will be used.

The IP address and port of the query API MUST be identified via the mDNS advertisement, with the HTTP path then being resolved via the standard NMOS API path documentation.

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

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", 
    "href": "http://172.29.176.102:12345/", 
    "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"
}

HTTP status code 404

Returned when the requested Node ID does not exist

Body

Media type: application/json

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

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

HTTP status code 404

Returned when the requested Source ID does not exist

Body

Media type: application/json

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

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", 
    "id": "b3bb5be7-9fe9-4324-a5bb-4c70e1084449"
}

HTTP status code 404

Returned when the requested Flow ID does not exist

Body

Media type: application/json

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

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", 
    "version": "1441723676:366608283", 
    "senders": [], 
    "id": "a370d258-69de-4422-860a-ee4cf32ee9f4", 
    "node_id": "3a25a674-e6eb-4987-84ad-ef479fe4d527",
    "type": "urn:x-nmos:device:pipeline"
}

HTTP status code 404

Returned when the requested Device ID does not exist

Body

Media type: application/json

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

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.0/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

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

HTTP status code 200

Body

Media type: application/json

Example:

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