-
Notifications
You must be signed in to change notification settings - Fork 23
/
QueryAPI.raml
476 lines (437 loc) · 20.8 KB
/
QueryAPI.raml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
#%RAML 1.0
# AMWA NMOS Discovery and Registration Specification: Query API
# (c) AMWA 2016
title: Query
baseUri: http://example.api.com/x-nmos/query/{version}
version: v1.2
mediaType: application/json
types:
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
ErrorSchema: !include schemas/error.json
traits:
paged:
description: API resource supporting pagination of results
queryParameters:
paging.since:
description: Return only the results which have been created/updated since the time specified (non-inclusive) (seconds:nanoseconds)
type: string
pattern: "^[0-9]+:[0-9]+$"
paging.until:
description: Return only the results which were created/updated up until the time specified (inclusive) (seconds:nanoseconds)
type: string
pattern: "^[0-9]+:[0-9]+$"
paging.limit:
description: Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
type: integer
paging.order:
description: 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
type: string
enum: ["create", "update"]
default: "update"
responses:
200:
headers:
Link:
description: Provides references to cursors for paging. The 'rel' attribute may be one of 'next', 'prev', 'first' or 'last'
type: string
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:
description: 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
type: integer
X-Paging-Since:
description: 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.
type: string
example: 1441716353:6839634
X-Paging-Until:
description: 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.
type: string
example: 1441716120:318744030
downgrade:
description: API resource supporting the return of data which matches an older minor API version than the request would return by default.
queryParameters:
query.downgrade:
description: Minimum API version to return resources from if they exists within the registry
type: string
pattern: "^v[0-9]+.[0-9]+$"
responses:
400:
description: The requested downgrade query moves between major API versions which is not permitted.
rql:
description: This resource MAY support advanced query formats using the Resource Query Language (RQL) syntax
queryParameters:
query.rql:
description: 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.
type: string
responses:
400:
description: The server refuses to perform the query as it would be too resource intensive.
501:
description: The query parameters specified are not currently supported by this implementation.
ancestry:
description: This resource MAY support ancestry tracking whereby an ID is traced through 'parents' attributes to find and return all related resources
queryParameters:
query.ancestry_id:
description: UUID of the Source or Flow for which the ancestry is to be tracked
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}$"
query.ancestry_type:
description: The type of ancestry query to perform, whether searching for 'parents' or 'children' of the specified resource
type: string
enum: ["parents", "children"]
query.ancestry_generations:
description: 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
type: integer
responses:
200:
headers:
X-Ancestry-Generations:
description: 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.
type: integer
400:
description: The server refuses to perform the query as it would be too resource intensive.
501:
description: The query parameters specified are not currently supported by this implementation.
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: DNS-SD Advertisement
content: |
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.
- title: DNS-SD TXT Records
content: |
**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.
- title: Websockets
content: |
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.
- title: Versioning
content: |
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.
- title: Query Parameters
content: |
As a Query API may provide access to many thousands of resources, query parameters provide the means to narrow down these results. Any attribute which may be returned by a particular API resource SHOULD be available to use as a query parameter, however this RAML documentation only explicitly identifies core attributes under 'queryParameters'.
For a full description of the expected querying behaviour along with examples, please see the [Query Parameters Documentation](../docs/2.5. APIs - Query Parameters.md).
Basic Queries and Downgrade Queries SHOULD be supported. Advanced queries using RQL, ancestry tracking and similar MAY be supported.
** Basic Queries **
Basic queries make use of standard HTTP GET query parameters in the form '?key=value'. Keys may match any attribute which the API schemas indicate could be returned by a given resource.
* Querying Within Objects
Querying using attributes of objects is permitted via the use of a '.' separator. For example, the /receivers resource may be queried with '?subscription.sender_id=2683ad14-642f-459d-a169-ef91c76cec6b'.
* Querying Within Arrays
Querying using attributes of objects held within arrays is permitted via the use of a '.' separator. For example, the /nodes resource may be queried with '?services.type=urn:x-manufacturer:service:tally'. More advanced queries within arrays may require use of the Resource Query Language 'in()' operator.
** Downgrade Queries **
In order to streamline upgrades from one API version to another a Query API may sit in front of a registry which holds registered data matching multiple API versions' schemas. By default the Query API must only return data matching the API version specified in the request URL, however the client may choose to request mixed versions of data if it is capable of handling the potential missing keys.
Downgrades MUST only be performed between minor API versions as major versions may remove or re-purpose attributes. Clients which support multiple major API versions should retrieve this data via multiple HTTP requests or websocket subscriptions.
** Resource Query Language **
Given the constraints of using a standard '?variable=value&variable2=value2' query syntax, Query APIs MAY support Resource Query Language (https://github.com/persvr/rql/) in order to support more advanced queries.
RQL should be formatted in the normalised form as opposed to using FIQL syntax, and passed via the query string using '?query.rql=...'.
Querying within objects and arrays should be performed as in the Basic Queries case by using the '.' separator.
When an RQL query is specified, the Basic Queries format MAY be ignored in order to simplify implementation.
Note that as RQL permits the definition of very complex queries, the server may return a 400 error code to indicate that it is refusing to action the client's request due to the query's complexity.
* Constraints
Not all RQL operators will be suitable for use with a Query API. It is suggested that the following operators are supported, however these are not mandated and implementations may choose to support their own subset.
1) Functions: in(), out(), select()
2) Logical Operators: and(), or(), not()
3) 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.
/:
displayName: Base
get:
description: List of paths available from this API
responses:
200:
body:
example: !include ../examples/queryapi-base-get-200.json
type: !include schemas/queryapi-base.json
/nodes:
displayName: Nodes
get:
is: [paged, rql, downgrade]
description: |
List Nodes.
NB: Query parameters should be implemented for all permitted resource attributes.
queryParameters:
id:
version:
label:
description:
tags:
responses:
200:
body:
example: !include ../examples/queryapi-nodes-get-200.json
type: 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:
is: [downgrade]
description: Get a single Node
responses:
200:
body:
example: !include ../examples/queryapi-nodeid-get-200.json
type: Node
404:
description: Returned when the requested Node ID does not exist
body:
type: ErrorSchema
/sources:
displayName: Sources
get:
is: [paged, rql, ancestry, downgrade]
description: |
List Sources.
NB: Query parameters should be implemented for all permitted resource attributes.
queryParameters:
id:
version:
label:
description:
tags:
responses:
200:
body:
example: !include ../examples/queryapi-sources-get-200.json
type: 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:
is: [downgrade]
description: Get a single Source
responses:
200:
body:
example: !include ../examples/queryapi-sourceid-get-200.json
type: Source
404:
description: Returned when the requested Source ID does not exist
body:
type: ErrorSchema
/flows:
displayName: Flows
get:
is: [paged, rql, ancestry, downgrade]
description: |
List Flows.
NB: Query parameters should be implemented for all permitted resource attributes.
queryParameters:
id:
version:
label:
description:
tags:
responses:
200:
body:
example: !include ../examples/queryapi-flows-get-200.json
type: 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:
is: [downgrade]
description: Get a single Flow
responses:
200:
body:
example: !include ../examples/queryapi-flowid-get-200.json
type: Flow
404:
description: Returned when the requested Flow ID does not exist
body:
type: ErrorSchema
/devices:
displayName: Devices
get:
is: [paged, rql, downgrade]
description: |
List Devices.
NB: Query parameters should be implemented for all permitted resource attributes.
queryParameters:
id:
version:
label:
description:
tags:
responses:
200:
body:
example: !include ../examples/queryapi-devices-get-200.json
type: 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:
is: [downgrade]
description: Get a single Device
responses:
200:
body:
example: !include ../examples/queryapi-deviceid-get-200.json
type: Device
404:
description: Returned when the requested Device ID does not exist
body:
type: ErrorSchema
/senders:
displayName: Senders
get:
is: [paged, rql, downgrade]
description: |
List Senders.
NB: Query parameters should be implemented for all permitted resource attributes.
queryParameters:
id:
version:
label:
description:
tags:
responses:
200:
body:
example: !include ../examples/queryapi-senders-get-200.json
type: 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:
is: [downgrade]
description: Get a single Sender
responses:
200:
body:
example: !include ../examples/queryapi-senderid-get-200.json
type: Sender
404:
description: Returned when the requested Sender ID does not exist
body:
type: ErrorSchema
/receivers:
displayName: Receivers
get:
is: [paged, rql, downgrade]
description: |
List Receivers.
NB: Query parameters should be implemented for all permitted resource attributes.
queryParameters:
id:
version:
label:
description:
tags:
responses:
200:
body:
example: !include ../examples/queryapi-receivers-get-200.json
type: 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:
is: [downgrade]
description: Get a single Receiver
responses:
200:
body:
example: !include ../examples/queryapi-receiverid-get-200.json
type: Receiver
404:
description: Returned when the requested Receiver ID does not exist
body:
type: ErrorSchema
/subscriptions:
displayName: Subscriptions
post:
description: Create a websocket subscription to an API resource
body:
example: !include ../examples/queryapi-subscriptions-post-request.json
type: !include schemas/queryapi-subscriptions-post-request.json
responses:
201:
body:
example: !include ../examples/queryapi-subscriptions-post-200.json
type: !include schemas/queryapi-subscription-response.json
200:
body:
example: !include ../examples/queryapi-subscriptions-post-200.json
type: !include schemas/queryapi-subscription-response.json
400:
description: Returned when the POST request is incorrectly formatted or missing mandatory attributes
body:
type: ErrorSchema
501:
description: The query parameters specified are not currently supported by this implementation.
body:
type: ErrorSchema
get:
is: [paged]
description: List active connections to websockets providing real-time updates on resource changes (for debug use only)
responses:
200:
body:
example: !include ../examples/queryapi-subscriptions-get-200.json
type: !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 (for debug use only)
responses:
200:
body:
example: !include ../examples/queryapi-subscriptionid-get-200.json
type: !include schemas/queryapi-subscription-response.json
404:
description: Returned when the requested Subscription ID does not exist
body:
type: ErrorSchema
delete:
description: Delete a single subscription
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:
type: ErrorSchema
404:
description: Returned when the requested Subscription ID does not exist
body:
type: ErrorSchema