Networked Media Open Specifications

APIs: Query Parameters

←APIs - Server Side Implementation · Index↑ · APIs - Discovery→

The Network Control API supports a range of query string parameters which may be used as part of GET requests.

The following document describes the expected usage and behaviour of these query parameters alongside the RAML specification in order to aid implementers. A description of each individual query parameter is included within the RAML.

Pagination

Network Control APIs SHOULD support pagination of their API resources where the ‘paged’ trait is specified in the RAML documentation. A 501 HTTP status code MUST be returned where pagination is attempted against a Network Control API which does not implement it.

Network Control API clients MUST detect whether pagination is being used by examining the HTTP response headers for ‘X-Paging-Limit’ which MUST be returned in all cases where pagination is in use.

The following implementation notes should be observed:

Examples

The following examples aim to identify how pagination should behave in the presence of a set of resource data. In order to avoid displaying full resource representations, the only data listed here is the ‘update’ timestamp associated with each registered record. The same procedures can be applied where ‘creation’ timestamps and the ‘?paging.order=create’ parameter are used instead.

Where a paging limit is not specified in a request the server’s default is used.

Sample Data: Network Flow Update Timestamps (Comma-Separated)

[0:1, 0:2, 0:3, 0:4, 0:5, 0:6, 0:7, 0:8, 0:9, 0:10, 0:11, 0:12, 0:13, 0:14, 0:15, 0:16, 0:17, 0:18, 0:19, 0:20]

Each of the above corresponds to the update timestamp of a corresponding Network Flow, in the format <seconds>:<nanoseconds> and displayed in ascending order. These will be used throughout the following examples.

Response payloads in the examples will show these values, but in a real implementation should be replaced by the corresponding JSON objects for the Network Flow or other resources being queried.

Example 1: Initial /network-flows Request

In this example there are no query parameters used in the request, but as the Network Control API supports pagination it returns a subset of the results with headers identifying how to page further into the collection.

Request

GET /x-nmos/netctrl/v1.0

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.since=0:20&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.until=0:10&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:10
X-Paging-Until: 0:20

Payload Resources

[
  0:20,
  0:19,
  0:18,
  0:17,
  0:16,
  0:15,
  0:14,
  0:13,
  0:12,
  0:11
]

Notes

Example 2: Request With Custom Limit

This request is similar to Example 1, but the client has chosen to use a custom page size limit.

Request

GET /x-nmos/netctrl/v1.0/network-flows?paging.limit=5

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.since=0:20&paging.limit=5>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.until=0:15&paging.limit=5>; rel="prev"
X-Paging-Limit: 5
X-Paging-Since: 0:15
X-Paging-Until: 0:20

Payload Resources

[
  0:20,
  0:19,
  0:18,
  0:17,
  0:16
]

Notes

Example 3: Request With Since Parameter

Request

GET /x-nmos/netctrl/v1.0/network-flows?paging.since=0:4

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.since=0:14&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.until=0:4&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:4
X-Paging-Until: 0:14

Payload Resources

[
  0:14,
  0:13,
  0:12,
  0:11,
  0:10,
  0:9,
  0:8,
  0:7,
  0:6,
  0:5
]

Example 4: Request With Until Parameter

Request

GET /x-nmos/netctrl/v1.0/network-flows?paging.until=0:16

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.since=0:16&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.until=0:6&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:6
X-Paging-Until: 0:16

Payload Resources

[
  0:16,
  0:15,
  0:14,
  0:13,
  0:12,
  0:11,
  0:10,
  0:9,
  0:8,
  0:7
]

Example 5: Request With Since & Until Parameters

Request

GET /x-nmos/netctrl/v1.0/network-flows?paging.since=0:4&paging.until=0:16

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.since=0:14&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.until=0:4&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:4
X-Paging-Until: 0:14

Payload Resources

[
  0:14,
  0:13,
  0:12,
  0:11,
  0:10,
  0:9,
  0:8,
  0:7,
  0:6,
  0:5
]

Notes

Edge Cases

When a client requests data which falls at the extreme ends of the stored data set it may be less clear what values should be returned in the ‘X-Paging-Limit’ and ‘X-Paging-Since’ headers. The following examples are intended to clarify the expectation in these cases.

Where a paging limit is not specified in a request the server’s default is used.

Example 1: Client request occurs at the beginning of the data set

Request

GET /x-nmos/netctrl/v1.0/network-flows?paging.until=0:20

In this case, assume that there are stored records for ‘0:21’ and ‘0:22’ but no earlier.

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.since=0:20&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.until=0:0&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:0
X-Paging-Until: 0:20

Payload Resources

[]

Example 2: Client request occurs at the end of the data set

Request

GET /x-nmos/netctrl/v1.0/network-flows?paging.since=0:20

In this case, assume that there are stored records for ‘0:19’ and ‘0:20’ but no later.

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.since=0:20&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?paging.until=0:20&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:20
X-Paging-Until: 0:20

Payload Resources

[]

Notes:

Example 3: Client request includes a query parameter resulting in a single result, but no paging parameters

Request

GET /x-nmos/netctrl/v1.0/network-flows?multicast_address=226.1.1.1

In this case, assume that the most recently created or updated Network Flow held in the registry has a paging value of ‘0:20’ associated with it. Also assume that the Network Flow with multicast address ‘226.1.1.1’ has a paging time of ‘0:15’.

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?multicast_address=226.1.1.1&paging.since=0:20&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?multicast_address=226.1.1.1&paging.until=0:0&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:0
X-Paging-Until: 0:20

Payload Resources

[
  0:15
]

Example 4: Client request includes a query parameter resulting in a no result, with no paging parameters

Request

GET /x-nmos/netctrl/v1.0/network-flows?multicast_address=224.1.0.37

In this case, assume that the most recently created or updated Network Flow held in the registry has a paging value of ‘0:20’ associated with it.

Response

Headers

Link: <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?multicast_address=224.1.0.37&paging.since=0:20&paging.limit=10>; rel="next", <http://example.api.com/x-nmos/netctrl/v1.0/network-flows/?multicast_address=224.1.0.37&paging.until=0:0&paging.limit=10>; rel="prev"
X-Paging-Limit: 10
X-Paging-Since: 0:0
X-Paging-Until: 0:20

Payload Resources

[]

Basic Queries

Network Control APIs SHOULD support basic queries against their API resources. A 501 HTTP status code MUST be returned where a basic query is attempted against a Network Control API which does not implement it.

Basic queries make use of standard HTTP GET query parameters in the form ‘?key1=value1&key2=value2’. Keys may match any attribute which the API schemas indicate could be returned by a given resource.

Any attribute which may be returned by a particular API resource SHOULD be available to use as a query parameter, however the RAML documentation only explicitly identifies core attributes under ‘queryParameters’.

If a query parameter is requested which does not match an attribute found in any resource, an empty result set must be returned.

Examples

Example 1: Basic Query Using One Parameter

Request

GET /x-nmos/netctrl/v1.0/endpoints?label=My%20Endpoint

Response

Example 2: Basic Query Using Two Parameters

Request

GET /x-nmos/netctrl/v1.0/endpoints?role=sender&chassis_id=2d-af-a9-41-01-b4

Response

Example 3: Querying Within Objects

Request

GET /x-nmos/netctrl/v1.0/endpoints?attached_network_device.chassis_id=7a-c9-d7-f0-e2-03

Response

Example 4: Querying Within Arrays

Request

GET /x-nmos/netctrl/v1.0/network-devices?interfaces.admin_status=up

Response

Invalid Examples

Invalid Example 1: Duplicate Query Parameters

Request

GET /x-nmos/netctrl/v1.0/network-links?peers.device_id=f3841396-1cbf-4a8a-915c-dd1034121532&peers.device_id=2c516096-4fa6-4b93-8b84-248ad79dff3a

Response

←APIs - Server Side Implementation · Index↑ · APIs - Discovery→