forked from AMWA-TV/is-04
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathNodeAPI.raml
262 lines (245 loc) · 9.91 KB
/
NodeAPI.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
#%RAML 0.8
# AMWA NMOS Discovery and Registration Specification: Node API
# (c) AMWA 2016
title: Node
baseUri: http://example.api.com/x-nmos/node/{version}
version: v1.1
mediaType: application/json
schemas:
- Node: !include schemas/node.json
Nodes: !include schemas/nodes.json
Device: !include schemas/device.json
Devices: !include schemas/devices.json
Source: !include schemas/source.json
Sources: !include schemas/sources.json
Flow: !include schemas/flow.json
Flows: !include schemas/flows.json
Sender: !include schemas/sender.json
Senders: !include schemas/senders.json
Receiver: !include schemas/receiver.json
Receivers: !include schemas/receivers.json
EmptySchema: !include schemas/empty.json
ErrorSchema: !include schemas/error.json
documentation:
- title: Overview
content: |
The Node API is exposed by each NMOS Node in a system, regardless of whether it is possible for that Node to provide NMOS resources such as Flows, Sources etc. Data exposed by the Node API is used to populate the (distributed) registry via the Registration API. In smaller deployments the Node API is fetched from directly as required by Nodes which implement the Peer to Peer specification.
- title: DNS-SD Advertisement
content: |
Node APIs MUST produce an mDNS advertisement of the type \_nmos-node.\_tcp. This MAY be accompanied by a unicast DNS announcement of the same type.
The IP address and port of the Node 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' (lower-case) dependent on the protocol in use by the Node 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.
**ver\_**
When a Node is unable to locate or successfully register with a Registration API it MUST additionally advertise the following mDNS TXT records as part of its Node advertisement. If a Node is successfully registered with a Registration API it MUST withdraw advertisements of these TXT records. There is no requirement to register these TXT records with a unicast DNS service.
| **TXT Record Name** | **Corresponding Node API Resource** |
|---------------------|-------------------------------------|
| ver\_slf | self |
| ver\_src | sources |
| ver\_flw | flows |
| ver\_dvc | devices |
| ver\_snd | senders |
| ver\_rcv | receivers |
The value of each of the above should be an unsigned 8-bit integer initialised to '0'. This integer MUST be incremented and mDNS TXT record updated whenever a change is made to the corresponding HTTP API resource on the Node. The integer must wrap back to a value of '0' after reaching a maximum value of '255' (MAX_UINT8_T).
For example, the 'ver_src' TXT record must be created when the Node first advertises itself via mDNS. If the data held within the HTTP resource for /sources is added to, removed from or edited, then the 'ver_src' text record must be modified (value incremented).
- title: Versioning
content: |
A Node 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: Receiver Subscriptions
content: |
A PUT request to /receivers/{receiverId}/target will modify which Sender a Receiver is subscribed to.
In order to 'subscribe' a Receiver to a Sender, a PUT request should be made to this resource containing a full Sender object.
In order to 'unsubscribe' a Receiver from a Sender, an empty object '{}' should be used in this PUT request.
In both cases the target resource should respond with a 202 code (accepted) on success, and a response body matching the request body.
The Receiver's subscription object contains a 'sender_id' attribute which must be updated once a Receiver has successfully requested, parsed and actioned a change to the manifest_href is it connected to.
/:
displayName: Base
get:
description: List of paths available from this API
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-base-get-200.json
schema: !include schemas/nodeapi-base.json
/self:
displayName: Self
get:
description: Get information about this Node
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-self-get-200.json
schema: Node
/sources:
displayName: Sources
get:
description: List Sources
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-sources-get-200.json
schema: Sources
/{sourceId}:
uriParameters:
sourceId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
get:
description: Get a single Source
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-sourceid-get-200.json
schema: Source
404:
description: Returned when the requested Source ID does not exist
body:
schema: ErrorSchema
/flows:
displayName: Flows
get:
description: List Flows
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-flows-get-200.json
schema: Flows
/{flowId}:
uriParameters:
flowId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
get:
description: Get a single Flow
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-flowid-get-200.json
schema: Flow
404:
description: Returned when the requested Flow ID does not exist
body:
schema: ErrorSchema
/devices:
displayName: Devices
get:
description: List Devices
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-devices-get-200.json
schema: Devices
/{deviceId}:
uriParameters:
deviceId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
get:
description: Get a single Device
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-deviceid-get-200.json
schema: Device
404:
description: Returned when the requested Device ID does not exist
body:
schema: ErrorSchema
/senders:
displayName: Senders
get:
description: List Senders
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-senders-get-200.json
schema: Senders
/{senderId}:
uriParameters:
senderId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
get:
description: Get a single Sender
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-senderid-get-200.json
schema: Sender
404:
description: Returned when the requested Sender ID does not exist
body:
schema: ErrorSchema
/receivers:
displayName: Receivers
get:
description: List Receivers
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-receivers-get-200.json
schema: Receivers
/{receiverId}:
uriParameters:
receiverId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
get:
description: Get a single Receiver
body:
schema: EmptySchema
responses:
200:
body:
example: !include ../examples/nodeapi-v1.1-receiverid-get-200.json
schema: Receiver
404:
description: Returned when the requested Receiver ID does not exist
body:
schema: ErrorSchema
/target:
put:
description: Request a change to a Receiver's subscription
body:
example: !include ../examples/nodeapi-v1.1-senderid-get-200.json
schema: Sender
responses:
202:
body:
example: !include ../examples/nodeapi-v1.1-senderid-get-200.json
schema: Sender
400:
description: Returned when the PUT request is incorrectly formatted or missing mandatory attributes
body:
schema: ErrorSchema
404:
description: Returned when the requested Receiver ID does not exist
body:
schema: ErrorSchema