Query API documentation version v1.2
http://example.api.com/x-nmos/query/{version}
- version: required(v1.2)
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.
Functions: in(), out(), select()
Logical Operators: and(), or(), not()
Relational Operators: eq(), ne(), gt(), ge(), lt(), le()
NB: It is suggested that sort() and limit() are 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
List of paths available from this API
get /
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
List Nodes. NB: Query parameters should be implemented for all permitted resource attributes.
get /nodes
List Nodes. NB: Query parameters should be implemented for all permitted resource attributes.
Query Parameters
- id: required(string)
- version: required(string)
- label: required(string)
- description: required(string)
- tags: required(string)
- paging.since: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
- paging.until: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
- paging.limit: required(integer)
Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
- paging.order: required(one of create, update - default: update)
Specify whether paging should be based upon initial resource creation time, or when it was last modified. In both cases the response should be provided in descending order
- query.rql: required(string)
RQL format string indicating the query to be performed, such as 'and(eq(format,urn:x-nmos:format:video),in(tags.location,(Salford,London)))'. Strings used as filter values MUST be URL encoded.
- 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
Headers
- Link: required(string)
Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
Example:
<http://example.api.com/x-nmos/query/{version}/nodes/?paging.since=1441716120:318744030&paging.limit=20>; rel="next", <http://example.api.com/x-nmos/query/{version}/nodes/?paging.until=1441716353:6839634&paging.limit=20>; rel="prev"
- X-Paging-Limit: required(integer)
Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
- X-Paging-Since: required(string)
Identifies the current value of the query parameter 'paging.since' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.until value of a query to return the previous page of results. Combining this with the X-Paging-Until header value provides the absolute time bounds of the current returned data set.
Example:
1441716353:6839634
- X-Paging-Until: required(string)
Identifies the current value of the query parameter 'paging.until' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.since value of a query to return the next page of results. Combining this with the X-Paging-Since header value provides the absolute time bounds of the current returned data set.
Example:
1441716120:318744030
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Node resources",
"title": "Collection of Nodes",
"items": {
"$ref": "node.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"version": "1441716120:318744030",
"hostname": "host1",
"label": "host1",
"description": "host1",
"tags": {},
"href": "http://172.29.176.102:12345/",
"api": {
"versions": ["v1.1", "v1.2"],
"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":"ptp",
"traceable": false,
"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"
}
]
},
{
"version": "1441716067:450064243",
"hostname": "host2",
"label": "host2",
"description": "host2",
"tags": {},
"href": "http://172.29.176.19:12345/",
"api": {
"versions": ["v1.1", "v1.2"],
"endpoints": [
{
"host": "172.29.176.19",
"port": 12345,
"protocol": "http"
}
]
},
"services": [
{
"href": "http://172.29.176.19:12345/x-manufacturer/pipelinemanager/",
"type": "urn:x-manufacturer:service:pipelinemanager"
},
{
"href": "http://172.29.176.19:12345/x-manufacturer/status/",
"type": "urn:x-manufacturer:service:status"
},
{
"href": "http://172.29.176.19:12345/x-manufacturer/mdnsbridge/",
"type": "urn:x-manufacturer:service:mdnsbridge"
}
],
"caps": {},
"id": "cebc6305-e8db-4026-aeb5-eb7a5620839e",
"clocks": [
{
"name": "clk0",
"ref_type":"ptp",
"traceable": false,
"version": "IEEE1588-2008",
"gmid": "08-00-11-ff-fe-21-e1-b0",
"locked": true
}
],
"interfaces" : [
{
"name":"en0",
"chassis_id":"a4-26-84-db-58-31",
"port_id":"a4-26-84-db-58-31"
},
{
"name":"en1",
"chassis_id":"a4-26-84-db-58-31",
"port_id":"a4-26-84-db-58-32"
}
]
}
]
HTTP status code 400
The server refuses to perform the query as it would be too resource intensive.
HTTP status code 501
The query parameters specified are not currently supported by this implementation.
Get a single Node
get /nodes/{nodeId}
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"]
}
}
}
}
}
},
"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"
}
}
}
},
"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"
}
}
}
}
}
}
]
}
Example:
{
"version": "1441716120:318744030",
"hostname": "host1",
"label": "host1",
"description": "host1",
"tags": {},
"href": "http://172.29.176.102:12345/",
"api": {
"versions": ["v1.1", "v1.2"],
"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"]
}
}
}
Sources
List Sources. NB: Query parameters should be implemented for all permitted resource attributes.
get /sources
List Sources. NB: Query parameters should be implemented for all permitted resource attributes.
Query Parameters
- id: required(string)
- version: required(string)
- label: required(string)
- description: required(string)
- tags: required(string)
- paging.since: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
- paging.until: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
- paging.limit: required(integer)
Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
- paging.order: required(one of create, update - default: update)
Specify whether paging should be based upon initial resource creation time, or when it was last modified. In both cases the response should be provided in descending order
- query.rql: required(string)
RQL format string indicating the query to be performed, such as 'and(eq(format,urn:x-nmos:format:video),in(tags.location,(Salford,London)))'. Strings used as filter values MUST be URL encoded.
- query.ancestry_id: 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}$)
UUID of the Source or Flow for which the ancestry is to be tracked
- query.ancestry_type: required(one of parents, children)
The type of ancestry query to perform, whether searching for 'parents' or 'children' of the specified resource
- query.ancestry_generations: required(integer)
The maximum number of generations to search through before returning the set of results. If this is not set, the server may use a default or fail to return results due to the request being too resource intensive
- 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
Headers
- Link: required(string)
Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
Example:
<http://example.api.com/x-nmos/query/{version}/nodes/?paging.since=1441716120:318744030&paging.limit=20>; rel="next", <http://example.api.com/x-nmos/query/{version}/nodes/?paging.until=1441716353:6839634&paging.limit=20>; rel="prev"
- X-Paging-Limit: required(integer)
Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
- X-Paging-Since: required(string)
Identifies the current value of the query parameter 'paging.since' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.until value of a query to return the previous page of results. Combining this with the X-Paging-Until header value provides the absolute time bounds of the current returned data set.
Example:
1441716353:6839634
- X-Paging-Until: required(string)
Identifies the current value of the query parameter 'paging.until' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.since value of a query to return the next page of results. Combining this with the X-Paging-Since header value provides the absolute time bounds of the current returned data set.
Example:
1441716120:318744030
- X-Ancestry-Generations: required(integer)
Identifies the number of ancestry generations being searched through. If 'query.ancestry_generations' is not specified by the user this should be returned as the server defined default.
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Source resources",
"title": "Collection of Sources",
"items": {
"$ref": "source.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "Camera 1",
"format": "urn:x-nmos:format:video",
"tags": {
"SourceDeviceType": [
"UHD Camera"
],
"host": [
"host1"
],
"location": [
"Location 1"
]
},
"caps": {},
"version": "1441724551:288670563",
"parents": [],
"label": "Camera 1",
"id": "042a4126-0208-443d-bda6-833ffc27ed51",
"device_id": "21a28338-fb2e-4df5-9b55-d58e6124bc9f",
"clock_name": "clk0"
},
{
"description": "Camera 2",
"format": "urn:x-nmos:format:video",
"tags": {
"SourceDeviceType": [
"HD Camera"
],
"host": [
"host2"
],
"Location": [
"Location 2"
]
},
"caps": {},
"version": "1441722516:851371645",
"parents": [],
"label": "CaptureCardSourceVideo",
"id": "c23c6a65-8e91-4f6c-a484-046363dbca29",
"device_id": "65fa8c20-890e-4b86-87b2-cfd9df91b7f8",
"clock_name": "clk0"
},
{
"description": "Audio 1",
"format": "urn:x-nmos:format:audio",
"tags": {
"host": [
"host3"
]
},
"caps": {},
"version": "1441719058:3226205",
"parents": [],
"label": "Audio 1",
"id": "62cf8dd3-015b-49e3-84c1-1d866a7540bc",
"device_id": "e7aa15c4-f793-4d43-a0cb-c638db6215ac",
"clock_name": "clk0",
"channels": [
{
"label": "Left Channel",
"symbol": "L"
},
{
"label": "Right Channel",
"symbol": "R"
}
]
},
{
"description": "Capture Card Source TR-04/2022-6",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:mux",
"caps": {},
"version": "1453880605:374934072",
"parents": [],
"label": "Capture Card Source TR-04/2022-6",
"id": "782fac41-17f6-4a21-8186-57ba63a1a8d3",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": "clk0"
},
{
"description": "Capture Card Source 2022-6 (No Refclock)",
"tags": {
"host": [
"host1"
]
},
"format": "urn:x-nmos:format:mux",
"caps": {},
"version": "1453880605:374934072",
"parents": [],
"label": "Capture Card Source 2022-6 (No Refclock)",
"id": "3ca37fce-c0cf-42a6-86ad-43635a53b5bb",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"clock_name": null
}
]
HTTP status code 400
The server refuses to perform the query as it would be too resource intensive.
HTTP status code 501
The query parameters specified are not currently supported by this implementation.
Get a single Source
get /sources/{sourceId}
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" }
]
}
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"]
}
}
}
Flows
List Flows. NB: Query parameters should be implemented for all permitted resource attributes.
get /flows
List Flows. NB: Query parameters should be implemented for all permitted resource attributes.
Query Parameters
- id: required(string)
- version: required(string)
- label: required(string)
- description: required(string)
- tags: required(string)
- paging.since: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
- paging.until: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
- paging.limit: required(integer)
Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
- paging.order: required(one of create, update - default: update)
Specify whether paging should be based upon initial resource creation time, or when it was last modified. In both cases the response should be provided in descending order
- query.rql: required(string)
RQL format string indicating the query to be performed, such as 'and(eq(format,urn:x-nmos:format:video),in(tags.location,(Salford,London)))'. Strings used as filter values MUST be URL encoded.
- query.ancestry_id: 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}$)
UUID of the Source or Flow for which the ancestry is to be tracked
- query.ancestry_type: required(one of parents, children)
The type of ancestry query to perform, whether searching for 'parents' or 'children' of the specified resource
- query.ancestry_generations: required(integer)
The maximum number of generations to search through before returning the set of results. If this is not set, the server may use a default or fail to return results due to the request being too resource intensive
- 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
Headers
- Link: required(string)
Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
Example:
<http://example.api.com/x-nmos/query/{version}/nodes/?paging.since=1441716120:318744030&paging.limit=20>; rel="next", <http://example.api.com/x-nmos/query/{version}/nodes/?paging.until=1441716353:6839634&paging.limit=20>; rel="prev"
- X-Paging-Limit: required(integer)
Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
- X-Paging-Since: required(string)
Identifies the current value of the query parameter 'paging.since' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.until value of a query to return the previous page of results. Combining this with the X-Paging-Until header value provides the absolute time bounds of the current returned data set.
Example:
1441716353:6839634
- X-Paging-Until: required(string)
Identifies the current value of the query parameter 'paging.until' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.since value of a query to return the next page of results. Combining this with the X-Paging-Since header value provides the absolute time bounds of the current returned data set.
Example:
1441716120:318744030
- X-Ancestry-Generations: required(integer)
Identifies the number of ancestry generations being searched through. If 'query.ancestry_generations' is not specified by the user this should be returned as the server defined default.
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Flow resources",
"title": "Collection of Flows",
"items": {
"$ref": "flow.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "Off-air proxy",
"format": "urn:x-nmos:format:video",
"tags": {},
"label": "Off-air proxy",
"version": "1441724130:194944510",
"parents": [],
"source_id": "c7b1c809-84d4-427d-b6bb-c8397c66ce2b",
"device_id": "a711ddd3-376d-4d6d-934d-834e54e045b1",
"id": "0c1f03d7-7e94-4b21-94d1-3ffbee8a0606",
"media_type": "video/H264",
"frame_width": 960,
"frame_height": 540,
"interlace_mode": "interlaced_tff",
"colorspace": "BT709"
},
{
"description": "Off-air",
"format": "urn:x-nmos:format:video",
"tags": {},
"label": "Off-air",
"version": "1441724130:186085940",
"parents": [],
"source_id": "c7b1c809-84d4-427d-b6bb-c8397c66ce2b",
"device_id": "a711ddd3-376d-4d6d-934d-834e54e045b1",
"id": "0e85d87b-4b19-4452-aea3-984c9f94bbc9",
"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
}
]
},
{
"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
},
{
"description": "TR-04 Video",
"tags": {},
"format": "urn:x-nmos:format:mux",
"label": "TR-04 Video",
"version": "1453880607:123995943",
"parents": [],
"source_id": "782fac41-17f6-4a21-8186-57ba63a1a8d3",
"device_id": "9126cc2f-4c26-4c9b-a6cd-93c4381c9be5",
"id": "4857f747-96cf-4ed7-8f4b-9497199f1f25",
"media_type": "video/SMPTE2022-6"
}
]
HTTP status code 400
The server refuses to perform the query as it would be too resource intensive.
HTTP status code 501
The query parameters specified are not currently supported by this implementation.
Get a single Flow
get /flows/{flowId}
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_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"]
}
}
}
Devices
List Devices. NB: Query parameters should be implemented for all permitted resource attributes.
get /devices
List Devices. NB: Query parameters should be implemented for all permitted resource attributes.
Query Parameters
- id: required(string)
- version: required(string)
- label: required(string)
- description: required(string)
- tags: required(string)
- paging.since: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
- paging.until: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
- paging.limit: required(integer)
Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
- paging.order: required(one of create, update - default: update)
Specify whether paging should be based upon initial resource creation time, or when it was last modified. In both cases the response should be provided in descending order
- query.rql: required(string)
RQL format string indicating the query to be performed, such as 'and(eq(format,urn:x-nmos:format:video),in(tags.location,(Salford,London)))'. Strings used as filter values MUST be URL encoded.
- 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
Headers
- Link: required(string)
Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
Example:
<http://example.api.com/x-nmos/query/{version}/nodes/?paging.since=1441716120:318744030&paging.limit=20>; rel="next", <http://example.api.com/x-nmos/query/{version}/nodes/?paging.until=1441716353:6839634&paging.limit=20>; rel="prev"
- X-Paging-Limit: required(integer)
Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
- X-Paging-Since: required(string)
Identifies the current value of the query parameter 'paging.since' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.until value of a query to return the previous page of results. Combining this with the X-Paging-Until header value provides the absolute time bounds of the current returned data set.
Example:
1441716353:6839634
- X-Paging-Until: required(string)
Identifies the current value of the query parameter 'paging.until' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.since value of a query to return the next page of results. Combining this with the X-Paging-Since header value provides the absolute time bounds of the current returned data set.
Example:
1441716120:318744030
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Device resources",
"title": "Collection of Devices",
"items": {
"$ref": "device.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"receivers": [],
"label": "pipeline 1 default device",
"description": "pipeline 1 default device",
"tags": {},
"version": "1441723957:582701772",
"senders": [
"c72cca5b-01db-47aa-bb00-03893defbfae",
"171d5c80-7fff-4c23-9383-46503eb1c63e",
"a2655c48-8a46-4c82-b9bc-98760d59d7f8"
],
"id": "c501ae64-f525-48b7-9816-c5e8931bc017",
"node_id": "1d452562-e1d5-4e84-b057-5c24de5f6b48",
"type": "urn:x-nmos:device:pipeline",
"controls": [
{
"type": "urn:x-manufacturer:control:generic",
"href": "http://124.54.36.2:465"
}
]
},
{
"receivers": [],
"label": "pipeline 1 default device",
"description": "pipeline 1 default device",
"tags": {},
"version": "1441976012:727999141",
"senders": [],
"id": "a30e4fba-254a-4e97-8bf7-daec80b8e57f",
"node_id": "3b8be755-08ff-452b-b217-c9151eb21193",
"type": "urn:x-nmos:device:pipeline",
"controls": []
},
{
"receivers": [
"a383178a-76cc-4894-9121-dc390c7847d3"
],
"label": "pipeline 1 default device",
"description": "pipeline 1 default device",
"tags": {},
"version": "1441722334:834709519",
"senders": [
"24da6ba7-b0aa-4883-a89a-2b867328dbf9"
],
"id": "e19ef82c-5f0a-48da-a86c-bb2377ab09a4",
"node_id": "4cf38bb4-d6c4-48d6-a086-6eac45d73ae5",
"type": "urn:x-nmos:device:pipeline",
"controls": []
},
{
"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 400
The server refuses to perform the query as it would be too resource intensive.
HTTP status code 501
The query parameters specified are not currently supported by this implementation.
Get a single Device
get /devices/{deviceId}
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": [
{
"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. 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"
}
}
}
}
}
}
]
}
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 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"]
}
}
}
Senders
List Senders. NB: Query parameters should be implemented for all permitted resource attributes.
get /senders
List Senders. NB: Query parameters should be implemented for all permitted resource attributes.
Query Parameters
- id: required(string)
- version: required(string)
- label: required(string)
- description: required(string)
- tags: required(string)
- paging.since: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
- paging.until: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
- paging.limit: required(integer)
Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
- paging.order: required(one of create, update - default: update)
Specify whether paging should be based upon initial resource creation time, or when it was last modified. In both cases the response should be provided in descending order
- query.rql: required(string)
RQL format string indicating the query to be performed, such as 'and(eq(format,urn:x-nmos:format:video),in(tags.location,(Salford,London)))'. Strings used as filter values MUST be URL encoded.
- 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
Headers
- Link: required(string)
Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
Example:
<http://example.api.com/x-nmos/query/{version}/nodes/?paging.since=1441716120:318744030&paging.limit=20>; rel="next", <http://example.api.com/x-nmos/query/{version}/nodes/?paging.until=1441716353:6839634&paging.limit=20>; rel="prev"
- X-Paging-Limit: required(integer)
Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
- X-Paging-Since: required(string)
Identifies the current value of the query parameter 'paging.since' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.until value of a query to return the previous page of results. Combining this with the X-Paging-Until header value provides the absolute time bounds of the current returned data set.
Example:
1441716353:6839634
- X-Paging-Until: required(string)
Identifies the current value of the query parameter 'paging.until' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.since value of a query to return the next page of results. Combining this with the X-Paging-Since header value provides the absolute time bounds of the current returned data set.
Example:
1441716120:318744030
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Sender resources",
"title": "Collection of Senders",
"items": {
"$ref": "sender.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "Camera 1",
"label": "Camera 1",
"manifest_href": "http://172.29.80.25/x-manufacturer/senders/4002d6b5-5775-4975-9859-5b330fcea288/stream.sdp",
"version": "1441724086:828491206",
"flow_id": "75bfddce-7142-4368-bb4a-8a82c837c6df",
"id": "4002d6b5-5775-4975-9859-5b330fcea288",
"transport": "urn:x-nmos:transport:rtp.mcast",
"interface_bindings":[
"eth0",
"eth1"
],
"device_id": "3a98e804-9871-4699-ba31-d608309d8933",
"caps": {},
"tags": {},
"subscription": {
"receiver_id": null,
"active": true
}
},
{
"description": "Camera 2",
"label": "Camera 2",
"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":[
"en0"
],
"device_id": "c501ae64-f525-48b7-9816-c5e8931bc017",
"caps": {},
"tags": {},
"subscription": {
"receiver_id": null,
"active": true
}
},
{
"description": "Camera 2 Audio",
"label": "Camera 2 Audio",
"manifest_href": "http://172.29.176.81/x-manufacturer/senders/bb793530-8fd7-49f9-8514-314126bbc624/stream.sdp",
"version": "1441724039:737277493",
"flow_id": "4ffa5719-9ab9-4395-bedb-3534fa7ba438",
"id": "bb793530-8fd7-49f9-8514-314126bbc624",
"transport": "urn:x-nmos:transport:rtp.mcast",
"interface_bindings":[
"en1"
],
"device_id": "5f88d383-596c-409c-887e-a90e42ef3684",
"caps": {},
"tags": {},
"subscription": {
"receiver_id": null,
"active": true
}
}
]
HTTP status code 400
The server refuses to perform the query as it would be too resource intensive.
HTTP status code 501
The query parameters specified are not currently supported by this implementation.
Get a single Sender
get /senders/{senderId}
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",
"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. 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 URL to a file describing how to connect to the Sender (SDP for RTP). The Sender's 'version' attribute should be updated if the contents of this file are modified. This URL may return an HTTP 404 where the 'active' parameter in the 'subscription' object is present and set to false (v1.2+ only).",
"type": "string",
"format": "uri"
},
"interface_bindings": {
"description": "Binding of Sender egress ports to interfaces on the parent Node. Should contain a single network interface unless a redundancy mechanism such as ST.2022-7 is in use, in which case each 'leg' should have its matching interface listed. Where the redundancy mechanism sends more than one copy of the stream via the same interface, that interface should be listed a corresponding number of times.",
"type": "array",
"items": {
"type":"string"
}
},
"subscription": {
"description": "Object containing the 'receiver_id' currently subscribed to (unicast only). Receiver_id should be null on initialisation, or when connected to a non-NMOS unicast Receiver.",
"type": "object",
"required": ["receiver_id", "active"],
"properties": {
"receiver_id": {
"type": ["string", "null"],
"description": "UUID of the Receiver that this Sender is currently subscribed to",
"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 stream data to a single Receiver (unicast), or to the network via multicast or a pull-based mechanism",
"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"]
}
}
}
Receivers
List Receivers. NB: Query parameters should be implemented for all permitted resource attributes.
get /receivers
List Receivers. NB: Query parameters should be implemented for all permitted resource attributes.
Query Parameters
- id: required(string)
- version: required(string)
- label: required(string)
- description: required(string)
- tags: required(string)
- paging.since: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
- paging.until: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
- paging.limit: required(integer)
Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
- paging.order: required(one of create, update - default: update)
Specify whether paging should be based upon initial resource creation time, or when it was last modified. In both cases the response should be provided in descending order
- query.rql: required(string)
RQL format string indicating the query to be performed, such as 'and(eq(format,urn:x-nmos:format:video),in(tags.location,(Salford,London)))'. Strings used as filter values MUST be URL encoded.
- 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
Headers
- Link: required(string)
Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
Example:
<http://example.api.com/x-nmos/query/{version}/nodes/?paging.since=1441716120:318744030&paging.limit=20>; rel="next", <http://example.api.com/x-nmos/query/{version}/nodes/?paging.until=1441716353:6839634&paging.limit=20>; rel="prev"
- X-Paging-Limit: required(integer)
Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
- X-Paging-Since: required(string)
Identifies the current value of the query parameter 'paging.since' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.until value of a query to return the previous page of results. Combining this with the X-Paging-Until header value provides the absolute time bounds of the current returned data set.
Example:
1441716353:6839634
- X-Paging-Until: required(string)
Identifies the current value of the query parameter 'paging.until' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.since value of a query to return the next page of results. Combining this with the X-Paging-Since header value provides the absolute time bounds of the current returned data set.
Example:
1441716120:318744030
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of Receiver resources",
"title": "Collection of Receivers",
"items": {
"$ref": "receiver.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"description": "RTP receiver 1",
"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 1",
"id": "3350d113-1593-4271-a7f5-f4974415bb8e",
"transport": "urn:x-nmos:transport:rtp",
"interface_bindings":[
"en0",
"en1"
],
"subscription": {
"sender_id": "55311762-8003-48fa-a645-0a0c7621ce45",
"active": true
}
},
{
"description": "RTP receiver 2",
"tags": {
"Location": [
"Location 2"
]
},
"format": "urn:x-nmos:format:video",
"caps": {
"media_types": [
"video/raw"
]
},
"device_id": "76aa31e5-c3a4-4639-8dbb-98a86dc32942",
"version": "1441726973:353560292",
"label": "Viewer 2",
"id": "3a1be8bd-6077-4933-aa7a-b42b13bdbe8e",
"transport": "urn:x-nmos:transport:rtp",
"interface_bindings":[
"eth0",
"eth1"
],
"subscription": {
"sender_id": "a325cfe1-47ee-4a23-9a5c-7b5fcb9c2bb2",
"active": true
}
},
{
"description": "Audio RX",
"tags": {},
"format": "urn:x-nmos:format:audio",
"caps": {
"media_types": [
"audio/L24",
"audio/L16"
]
},
"device_id": "e19ef82c-5f0a-48da-a86c-bb2377ab09a4",
"version": "1441722334:801293520",
"label": "Audio RX",
"id": "a383178a-76cc-4894-9121-dc390c7847d3",
"transport": "urn:x-nmos:transport:rtp",
"interface_bindings":[
"eth0"
],
"subscription": {
"sender_id": null,
"active": false
}
}
]
HTTP status code 400
The server refuses to perform the query as it would be too resource intensive.
HTTP status code 501
The query parameters specified are not currently supported by this implementation.
Get a single Receiver
get /receivers/{receiverId}
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"]
}
}
}
Subscriptions
Create a websocket subscription to an API resource
List active connections to websockets providing real-time updates on resource changes (for debug use only)
post /subscriptions
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"
}
}
}
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
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"
}
}
}
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
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"
}
}
}
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
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 /subscriptions
List active connections to websockets providing real-time updates on resource changes (for debug use only)
Query Parameters
- paging.since: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
- paging.until: required(string - pattern: ^[0-9]+:[0-9]+$)
Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
- paging.limit: required(integer)
Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
- paging.order: required(one of create, update - default: update)
Specify whether paging should be based upon initial resource creation time, or when it was last modified. In both cases the response should be provided in descending order
HTTP status code 200
Headers
- Link: required(string)
Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
Example:
<http://example.api.com/x-nmos/query/{version}/nodes/?paging.since=1441716120:318744030&paging.limit=20>; rel="next", <http://example.api.com/x-nmos/query/{version}/nodes/?paging.until=1441716353:6839634&paging.limit=20>; rel="prev"
- X-Paging-Limit: required(integer)
Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
- X-Paging-Since: required(string)
Identifies the current value of the query parameter 'paging.since' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.until value of a query to return the previous page of results. Combining this with the X-Paging-Until header value provides the absolute time bounds of the current returned data set.
Example:
1441716353:6839634
- X-Paging-Until: required(string)
Identifies the current value of the query parameter 'paging.until' in use, or if not specified identifies what value it would have had to return this data set. This value may be re-used as the paging.since value of a query to return the next page of results. Combining this with the X-Paging-Since header value provides the absolute time bounds of the current returned data set.
Example:
1441716120:318744030
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "A list of subscription resources",
"title": "Collection of subscriptions",
"items": {
"$ref": "queryapi-subscription-response.json"
},
"minItems": 0,
"uniqueItems": true
}
Example:
[
{
"max_update_rate_ms": 100,
"resource_path": "/receivers",
"params": {},
"persist": false,
"secure": false,
"ws_href": "ws://172.29.80.52:8870/ws/?uid=6a52dbd5-a737-4c4e-823f-909ade8f8bf4",
"id": "6a52dbd5-a737-4c4e-823f-909ade8f8bf4"
},
{
"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"
},
{
"max_update_rate_ms": 100,
"resource_path": "/senders",
"params": {},
"persist": false,
"secure": true,
"ws_href": "wss://172.29.80.52:8870/ws/?uid=c5f5c1ad-f9e6-44c0-828f-da3f7cdef286",
"id": "c5f5c1ad-f9e6-44c0-828f-da3f7cdef286"
},
{
"max_update_rate_ms": 100,
"resource_path": "/flows",
"params": {},
"persist": false,
"secure": false,
"ws_href": "ws://172.29.80.52:8870/ws/?uid=b0416004-f825-4623-bf90-575b5dd32f93",
"id": "b0416004-f825-4623-bf90-575b5dd32f93"
}
]
Get a single subscription (for debug use only)
Delete a single subscription
get /subscriptions/{subscriptionId}
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"
}
}
}
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
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"]
}
}
}
delete /subscriptions/{subscriptionId}
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"]
}
}
}