QueryAPI
This API definition uses RAML 0.8, which is not supported by the shared HTML renderer. The source is shown below.
#%RAML 0.8
# AMWA NMOS Discovery and Registration Specification: Query API
# (c) AMWA 2016
title: Query
baseUri: http://example.api.com/x-nmos/query/{version}
version: v1.0
mediaType: application/json
schemas:
- Node: !include schemas/node.json
Nodes: !include schemas/nodes.json
Device: !include schemas/device.json
Devices: !include schemas/devices.json
Source: !include schemas/source.json
Sources: !include schemas/sources.json
Flow: !include schemas/flow.json
Flows: !include schemas/flows.json
Sender: !include schemas/sender.json
Senders: !include schemas/senders.json
Receiver: !include schemas/receiver.json
Receivers: !include schemas/receivers.json
EmptySchema: !include schemas/empty.json
ErrorSchema: !include schemas/error.json
documentation:
- title: Overview
content: |
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.
- title: mDNS Advertisement
content: |
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.
/:
displayName: Base
get:
description: List of paths available from this API
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-base-get-200.json
schema: !include schemas/queryapi-base.json
/nodes:
displayName: Nodes
get:
description: List Nodes
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-nodes-get-200.json
schema: Nodes
/{nodeId}:
uriParameters:
nodeId:
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}$"
get:
description: Get a single Node
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-nodeid-get-200.json
schema: Node
404:
description: Returned when the requested Node ID does not exist
body:
schema: ErrorSchema
/sources:
displayName: Sources
get:
description: List Sources
body:
schema: EmptySchema
queryParameters:
device_id:
label:
description:
format:
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-sources-get-200.json
schema: Sources
/{sourceId}:
uriParameters:
sourceId:
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}$"
get:
description: Get a single Source
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-sourceid-get-200.json
schema: Source
404:
description: Returned when the requested Source ID does not exist
body:
schema: ErrorSchema
/flows:
displayName: Flows
get:
description: List Flows
body:
schema: EmptySchema
queryParameters:
source_id:
label:
description:
format:
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-flows-get-200.json
schema: Flows
/{flowId}:
uriParameters:
flowId:
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}$"
get:
description: Get a single Flow
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-flowid-get-200.json
schema: Flow
404:
description: Returned when the requested Flow ID does not exist
body:
schema: ErrorSchema
/devices:
displayName: Devices
get:
description: List Devices
body:
schema: EmptySchema
queryParameters:
node_id:
label:
description:
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-devices-get-200.json
schema: Devices
/{deviceId}:
uriParameters:
deviceId:
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}$"
get:
description: Get a single Device
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-deviceid-get-200.json
schema: Device
404:
description: Returned when the requested Device ID does not exist
body:
schema: ErrorSchema
/senders:
displayName: Senders
get:
description: List Senders
body:
schema: EmptySchema
queryParameters:
flow_id:
label:
description:
transport:
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-senders-get-200.json
schema: Senders
/{senderId}:
uriParameters:
senderId:
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}$"
get:
description: Get a single Sender
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-senderid-get-200.json
schema: Sender
404:
description: Returned when the requested Sender ID does not exist
body:
schema: ErrorSchema
/receivers:
displayName: Receivers
get:
description: List Receivers
body:
schema: EmptySchema
queryParameters:
label:
description:
format:
transport:
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-receivers-get-200.json
schema: Receivers
/{receiverId}:
uriParameters:
receiverId:
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}$"
get:
description: Get a single Receiver
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-receiverid-get-200.json
schema: Receiver
404:
description: Returned when the requested Receiver ID does not exist
body:
schema: ErrorSchema
/subscriptions:
displayName: Subscriptions
post:
description: Create a websocket subscription to an API resource
body:
example: !include ../examples/queryapi-v1.0-subscriptions-post-request.json
schema: !include schemas/queryapi-v1.0-subscriptions-post-request.json
responses:
201:
body:
example: !include ../examples/queryapi-v1.0-subscriptions-post-200.json
schema: !include schemas/queryapi-subscription-response.json
200:
body:
example: !include ../examples/queryapi-v1.0-subscriptions-post-200.json
schema: !include schemas/queryapi-subscription-response.json
400:
description: Returned when the POST request is incorrectly formatted or missing mandatory attributes
body:
schema: ErrorSchema
get:
description: List active connections to websockets providing real-time updates on resource changes
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-subscriptions-get-200.json
schema: !include schemas/queryapi-subscriptions-response.json
/{subscriptionId}:
uriParameters:
subscriptionId:
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}$"
get:
description: Get a single subscription
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/queryapi-v1.0-subscriptionid-get-200.json
schema: !include schemas/queryapi-subscription-response.json
404:
description: Returned when the requested Subscription ID does not exist
body:
schema: ErrorSchema
delete:
description: Delete a single subscription
body:
schema: EmptySchema
responses:
204:
description: The expected response, indicating 'No Content' following the DELETE
403:
description: Returned when a DELETE request is made against a non-persistent subscription which is managed by the Query API and cannot be deleted
body:
schema: ErrorSchema
404:
description: Returned when the requested Subscription ID does not exist
body:
schema: ErrorSchema