ARI: bridges/{bridgeID}/addChannel: add roles parameter
[asterisk/asterisk.git] / rest-api / api-docs / bridges.json
1 {
2         "_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.",
3         "_author": "David M. Lee, II <dlee@digium.com>",
4         "_svn_revision": "$Revision$",
5         "apiVersion": "0.0.1",
6         "swaggerVersion": "1.1",
7         "basePath": "http://localhost:8088/stasis",
8         "resourcePath": "/api-docs/bridges.{format}",
9         "apis": [
10                 {
11                         "path": "/bridges",
12                         "description": "Active bridges",
13                         "operations": [
14                                 {
15                                         "httpMethod": "GET",
16                                         "summary": "List active bridges.",
17                                         "nickname": "getBridges",
18                                         "responseClass": "List[Bridge]"
19                                 },
20                                 {
21                                         "httpMethod": "POST",
22                                         "summary": "Create a new bridge.",
23                                         "notes": "This bridge persists until it has been shut down, or Asterisk has been shut down.",
24                                         "nickname": "newBridge",
25                                         "responseClass": "Bridge",
26                                         "parameters": [
27                                                 {
28                                                         "name": "type",
29                                                         "description": "Type of bridge to create.",
30                                                         "paramType": "query",
31                                                         "required": false,
32                                                         "allowMultiple": false,
33                                                         "dataType": "string",
34                                                         "allowableValues": {
35                                                                 "valueType": "LIST",
36                                                                 "values": [
37                                                                         "mixing",
38                                                                         "holding"
39                                                                 ]
40                                                         }
41                                                 }
42                                         ]
43                                 }
44                         ]
45                 },
46                 {
47                         "path": "/bridges/{bridgeId}",
48                         "description": "Individual bridge",
49                         "operations": [
50                                 {
51                                         "httpMethod": "GET",
52                                         "summary": "Get bridge details.",
53                                         "nickname": "getBridge",
54                                         "responseClass": "Bridge",
55                                         "parameters": [
56                                                 {
57                                                         "name": "bridgeId",
58                                                         "description": "Bridge's id",
59                                                         "paramType": "path",
60                                                         "required": true,
61                                                         "allowMultiple": false,
62                                                         "dataType": "string"
63                                                 }
64                                         ],
65                                         "errorResponses": [
66                                                 {
67                                                         "code": 404,
68                                                         "reason": "Bridge not found"
69                                                 }
70                                         ]
71                                 },
72                                 {
73                                         "httpMethod": "DELETE",
74                                         "summary": "Shut down a bridge.",
75                                         "notes": "If any channels are in this bridge, they will be removed and resume whatever they were doing beforehand.",
76                                         "nickname": "deleteBridge",
77                                         "responseClass": "void",
78                                         "parameters": [
79                                                 {
80                                                         "name": "bridgeId",
81                                                         "description": "Bridge's id",
82                                                         "paramType": "path",
83                                                         "required": true,
84                                                         "allowMultiple": false,
85                                                         "dataType": "string"
86                                                 }
87                                         ],
88                                         "errorResponses": [
89                                                 {
90                                                         "code": 404,
91                                                         "reason": "Bridge not found"
92                                                 }
93                                         ]
94                                 }
95                         ]
96                 },
97                 {
98                         "path": "/bridges/{bridgeId}/addChannel",
99                         "description": "Add a channel to a bridge",
100                         "operations": [
101                                 {
102                                         "httpMethod": "POST",
103                                         "summary": "Add a channel to a bridge.",
104                                         "nickname": "addChannelToBridge",
105                                         "responseClass": "void",
106                                         "parameters": [
107                                                 {
108                                                         "name": "bridgeId",
109                                                         "description": "Bridge's id",
110                                                         "paramType": "path",
111                                                         "required": true,
112                                                         "allowMultiple": false,
113                                                         "dataType": "string"
114                                                 },
115                                                 {
116                                                         "name": "channel",
117                                                         "description": "Ids of channels to add to bridge",
118                                                         "paramType": "query",
119                                                         "required": true,
120                                                         "allowMultiple": true,
121                                                         "dataType": "string"
122                                                 },
123                                                 {
124                                                         "name": "role",
125                                                         "description": "Channel's role in the bridge",
126                                                         "paramType": "query",
127                                                         "required": false,
128                                                         "allowMultiple": false,
129                                                         "dataType": "string"
130                                                 }
131                                         ],
132                                         "errorResponses": [
133                                                 {
134                                                         "code": 404,
135                                                         "reason": "Bridge not found"
136                                                 },
137                                                 {
138                                                         "code": 409,
139                                                         "reason": "Bridge not in Stasis application"
140                                                 },
141                                                 {
142                                                         "code": 422,
143                                                         "reason": "Channel not found, or not in Stasis application"
144                                                 }
145                                         ]
146                                 }
147                         ]
148                 },
149                 {
150                         "path": "/bridges/{bridgeId}/removeChannel",
151                         "description": "Remove a channel from a bridge",
152                         "operations": [
153                                 {
154                                         "httpMethod": "POST",
155                                         "summary": "Remove a channel from a bridge.",
156                                         "nickname": "removeChannelFromBridge",
157                                         "responseClass": "void",
158                                         "parameters": [
159                                                 {
160                                                         "name": "bridgeId",
161                                                         "description": "Bridge's id",
162                                                         "paramType": "path",
163                                                         "required": true,
164                                                         "allowMultiple": false,
165                                                         "dataType": "string"
166                                                 },
167                                                 {
168                                                         "name": "channel",
169                                                         "description": "Ids of channels to remove from bridge",
170                                                         "paramType": "query",
171                                                         "required": true,
172                                                         "allowMultiple": true,
173                                                         "dataType": "string"
174                                                 }
175                                         ]
176                                 }
177                         ]
178                 },
179                 {
180                         "path": "/bridges/{bridgeId}/play",
181                         "description": "Play media to the participants of a bridge",
182                         "operations": [
183                                 {
184                                         "httpMethod": "POST",
185                                         "summary": "Start playback of media on a bridge.",
186                                         "notes": "The media URI may be any of a number of URI's. You may use http: and https: URI's, as well as sound: and recording: URI's. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
187                                         "nickname": "playOnBridge",
188                                         "responseClass": "Playback",
189                                         "parameters": [
190                                                 {
191                                                         "name": "bridgeId",
192                                                         "description": "Bridge's id",
193                                                         "paramType": "path",
194                                                         "required": true,
195                                                         "allowMultiple": false,
196                                                         "dataType": "string"
197                                                 },
198                                                 {
199                                                         "name": "media",
200                                                         "description": "Media's URI to play.",
201                                                         "paramType": "query",
202                                                         "required": true,
203                                                         "allowMultiple": false,
204                                                         "dataType": "string"
205                                                 },
206                                                 {
207                                                         "name": "lang",
208                                                         "description": "For sounds, selects language for sound.",
209                                                         "paramType": "query",
210                                                         "required": false,
211                                                         "allowMultiple": false,
212                                                         "dataType": "string"
213                                                 },
214                                                 {
215                                                         "name": "offsetms",
216                                                         "description": "Number of media to skip before playing.",
217                                                         "paramType": "query",
218                                                         "required": false,
219                                                         "allowMultiple": false,
220                                                         "dataType": "int",
221                                                         "defaultValue": 0,
222                                                         "allowableValues": {
223                                                                 "valueType": "RANGE",
224                                                                 "min": 0
225                                                         }
226
227                                                 },
228                                                 {
229                                                         "name": "skipms",
230                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
231                                                         "paramType": "query",
232                                                         "required": false,
233                                                         "allowMultiple": false,
234                                                         "dataType": "int",
235                                                         "defaultValue": 3000,
236                                                         "allowableValues": {
237                                                                 "valueType": "RANGE",
238                                                                 "min": 0
239                                                         }
240
241                                                 }
242                                         ],
243                                         "errorResponses": [
244                                                 {
245                                                         "code": 404,
246                                                         "reason": "Bridge not found"
247                                                 },
248                                                 {
249                                                         "code": 409,
250                                                         "reason": "Bridge not in a Stasis application"
251                                                 }
252                                         ]
253                                 }
254                         ]
255                 },
256                 {
257                         "path": "/bridges/{bridgeId}/record",
258                         "description": "Record audio on a bridge",
259                         "operations": [
260                                 {
261                                         "httpMethod": "POST",
262                                         "summary": "Start a recording.",
263                                         "notes": "This records the mixed audio from all channels participating in this bridge.",
264                                         "nickname": "recordBridge",
265                                         "responseClass": "LiveRecording",
266                                         "parameters": [
267                                                 {
268                                                         "name": "bridgeId",
269                                                         "description": "Bridge's id",
270                                                         "paramType": "path",
271                                                         "required": true,
272                                                         "allowMultiple": false,
273                                                         "dataType": "string"
274                                                 },
275                                                 {
276                                                         "name": "name",
277                                                         "description": "Recording's filename",
278                                                         "paramType": "query",
279                                                         "required": true,
280                                                         "allowMultiple": false,
281                                                         "dataType": "string"
282                                                 },
283                                                 {
284                                                         "name": "format",
285                                                         "description": "Format to encode audio in",
286                                                         "paramType": "query",
287                                                         "required": true,
288                                                         "allowMultiple": false,
289                                                         "dataType": "string"
290                                                 },
291                                                 {
292                                                         "name": "maxDurationSeconds",
293                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit.",
294                                                         "paramType": "query",
295                                                         "required": false,
296                                                         "allowMultiple": false,
297                                                         "dataType": "int",
298                                                         "defaultValue": 0,
299                                                         "allowableValues": {
300                                                                 "valueType": "RANGE",
301                                                                 "min": 0
302                                                         }
303                                                 },
304                                                 {
305                                                         "name": "maxSilenceSeconds",
306                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit.",
307                                                         "paramType": "query",
308                                                         "required": false,
309                                                         "allowMultiple": false,
310                                                         "dataType": "int",
311                                                         "defaultValue": 0,
312                                                         "allowableValues": {
313                                                                 "valueType": "RANGE",
314                                                                 "min": 0
315                                                         }
316                                                 },
317                                                 {
318                                                         "name": "ifExists",
319                                                         "description": "Action to take if a recording with the same name already exists.",
320                                                         "paramType": "query",
321                                                         "required": false,
322                                                         "allowMultiple": false,
323                                                         "dataType": "string",
324                                                         "defaultValue": "fail",
325                                                         "allowableValues": {
326                                                                 "valueType": "LIST",
327                                                                 "values": [
328                                                                         "fail",
329                                                                         "overwrite",
330                                                                         "append"
331                                                                 ]
332                                                         }
333                                                 },
334                                                 {
335                                                         "name": "beep",
336                                                         "description": "Play beep when recording begins",
337                                                         "paramType": "query",
338                                                         "required": false,
339                                                         "allowMultiple": false,
340                                                         "dataType": "boolean",
341                                                         "defaultValue": false
342                                                 },
343                                                 {
344                                                         "name": "terminateOn",
345                                                         "description": "DTMF input to terminate recording.",
346                                                         "paramType": "query",
347                                                         "required": false,
348                                                         "allowMultiple": false,
349                                                         "dataType": "string",
350                                                         "defaultValue": "none",
351                                                         "allowableValues": {
352                                                                 "valueType": "LIST",
353                                                                 "values": [
354                                                                         "none",
355                                                                         "any",
356                                                                         "*",
357                                                                         "#"
358                                                                 ]
359                                                         }
360                                                 }
361                                         ]
362                                 }
363                         ]
364                 }
365         ],
366         "models": {
367                 "Bridge": {
368                         "id": "Bridge",
369                         "description": "The merging of media from one or more channels.\n\nEveryone on the bridge receives the same audio.",
370                         "properties": {
371                                 "id": {
372                                         "type": "string",
373                                         "description": "Unique identifier for this bridge",
374                                         "required": true
375                                 },
376                                 "technology": {
377                                         "type": "string",
378                                         "description": "Name of the current bridging technology",
379                                         "required": true
380                                 },
381                                 "bridge_type": {
382                                         "type": "string",
383                                         "description": "Type of bridge technology",
384                                         "required": true,
385                                         "allowableValues": {
386                                                 "valueType": "LIST",
387                                                 "values": [
388                                                         "mixing",
389                                                         "holding"
390                                                 ]
391                                         }
392                                 },
393                                 "bridge_class": {
394                                         "type": "string",
395                                         "description": "Bridging class",
396                                         "required": true
397                                 },
398                                 "channels": {
399                                         "type": "List[string]",
400                                         "description": "Ids of channels participating in this bridge",
401                                         "required": true
402                                 }
403                         }
404                 }
405         }
406 }