ARI: Adding a channel to a bridge while a live recording is active blocks
[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 all active bridges in Asterisk.",
17                                         "nickname": "list",
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": "create",
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": "get",
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": "destroy",
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": "addChannel",
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": 400,
135                                                         "reason": "Channel not found"
136                                                 },
137                                                 {
138                                                         "code": 404,
139                                                         "reason": "Bridge not found"
140                                                 },
141                                                 {
142                                                         "code": 409,
143                                                         "reason": "Bridge not in Stasis application; Channel currently recording"
144                                                 },
145                                                 {
146                                                         "code": 422,
147                                                         "reason": "Channel not in Stasis application"
148                                                 }
149                                         ]
150                                 }
151                         ]
152                 },
153                 {
154                         "path": "/bridges/{bridgeId}/removeChannel",
155                         "description": "Remove a channel from a bridge",
156                         "operations": [
157                                 {
158                                         "httpMethod": "POST",
159                                         "summary": "Remove a channel from a bridge.",
160                                         "nickname": "removeChannel",
161                                         "responseClass": "void",
162                                         "parameters": [
163                                                 {
164                                                         "name": "bridgeId",
165                                                         "description": "Bridge's id",
166                                                         "paramType": "path",
167                                                         "required": true,
168                                                         "allowMultiple": false,
169                                                         "dataType": "string"
170                                                 },
171                                                 {
172                                                         "name": "channel",
173                                                         "description": "Ids of channels to remove from bridge",
174                                                         "paramType": "query",
175                                                         "required": true,
176                                                         "allowMultiple": true,
177                                                         "dataType": "string"
178                                                 }
179                                         ],
180                                         "errorResponses": [
181                                                 {
182                                                         "code": 400,
183                                                         "reason": "Channel not found"
184                                                 },
185                                                 {
186                                                         "code": 404,
187                                                         "reason": "Bridge not found"
188                                                 },
189                                                 {
190                                                         "code": 409,
191                                                         "reason": "Bridge not in Stasis application"
192                                                 },
193                                                 {
194                                                         "code": 422,
195                                                         "reason": "Channel not in this bridge"
196                                                 }
197                                         ]
198                                 }
199                         ]
200                 },
201                 {
202                         "path": "/bridges/{bridgeId}/moh",
203                         "description": "Play music on hold to a bridge",
204                         "operations": [
205                                 {
206                                         "httpMethod": "POST",
207                                         "summary": "Play music on hold to a bridge or change the MOH class that is playing.",
208                                         "nickname": "startMoh",
209                                         "responseClass": "void",
210                                         "parameters": [
211                                                 {
212                                                         "name": "bridgeId",
213                                                         "description": "Bridge's id",
214                                                         "paramType": "path",
215                                                         "required": true,
216                                                         "allowMultiple": false,
217                                                         "dataType": "string"
218                                                 },
219                                                 {
220                                                         "name": "mohClass",
221                                                         "description": "Channel's id",
222                                                         "paramType": "query",
223                                                         "required": false,
224                                                         "allowMultiple": false,
225                                                         "dataType": "string"
226                                                 }
227                                         ],
228                                         "errorResponses": [
229                                                 {
230                                                         "code": 404,
231                                                         "reason": "Bridge not found"
232                                                 },
233                                                 {
234                                                         "code": 409,
235                                                         "reason": "Bridge not in Stasis application"
236                                                 }
237                                         ]
238                                 },
239                                 {
240                                         "httpMethod": "DELETE",
241                                         "summary": "Stop playing music on hold to a bridge.",
242                                         "notes": "This will only stop music on hold being played via POST bridges/{bridgeId}/moh.",
243                                         "nickname": "stopMoh",
244                                         "responseClass": "void",
245                                         "parameters": [
246                                                 {
247                                                         "name": "bridgeId",
248                                                         "description": "Bridge's id",
249                                                         "paramType": "path",
250                                                         "required": true,
251                                                         "allowMultiple": false,
252                                                         "dataType": "string"
253                                                 }
254                                         ],
255                                         "errorResponses": [
256                                                 {
257                                                         "code": 404,
258                                                         "reason": "Bridge not found"
259                                                 },
260                                                 {
261                                                         "code": 409,
262                                                         "reason": "Bridge not in Stasis application"
263                                                 }
264                                         ]
265                                 }
266                         ]
267                 },
268                 {
269                         "path": "/bridges/{bridgeId}/play",
270                         "description": "Play media to the participants of a bridge",
271                         "operations": [
272                                 {
273                                         "httpMethod": "POST",
274                                         "summary": "Start playback of media on a bridge.",
275                                         "notes": "The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
276                                         "nickname": "play",
277                                         "responseClass": "Playback",
278                                         "parameters": [
279                                                 {
280                                                         "name": "bridgeId",
281                                                         "description": "Bridge's id",
282                                                         "paramType": "path",
283                                                         "required": true,
284                                                         "allowMultiple": false,
285                                                         "dataType": "string"
286                                                 },
287                                                 {
288                                                         "name": "media",
289                                                         "description": "Media's URI to play.",
290                                                         "paramType": "query",
291                                                         "required": true,
292                                                         "allowMultiple": false,
293                                                         "dataType": "string"
294                                                 },
295                                                 {
296                                                         "name": "lang",
297                                                         "description": "For sounds, selects language for sound.",
298                                                         "paramType": "query",
299                                                         "required": false,
300                                                         "allowMultiple": false,
301                                                         "dataType": "string"
302                                                 },
303                                                 {
304                                                         "name": "offsetms",
305                                                         "description": "Number of media to skip before playing.",
306                                                         "paramType": "query",
307                                                         "required": false,
308                                                         "allowMultiple": false,
309                                                         "dataType": "int",
310                                                         "defaultValue": 0,
311                                                         "allowableValues": {
312                                                                 "valueType": "RANGE",
313                                                                 "min": 0
314                                                         }
315
316                                                 },
317                                                 {
318                                                         "name": "skipms",
319                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
320                                                         "paramType": "query",
321                                                         "required": false,
322                                                         "allowMultiple": false,
323                                                         "dataType": "int",
324                                                         "defaultValue": 3000,
325                                                         "allowableValues": {
326                                                                 "valueType": "RANGE",
327                                                                 "min": 0
328                                                         }
329
330                                                 }
331                                         ],
332                                         "errorResponses": [
333                                                 {
334                                                         "code": 404,
335                                                         "reason": "Bridge not found"
336                                                 },
337                                                 {
338                                                         "code": 409,
339                                                         "reason": "Bridge not in a Stasis application"
340                                                 }
341                                         ]
342                                 }
343                         ]
344                 },
345                 {
346                         "path": "/bridges/{bridgeId}/record",
347                         "description": "Record audio on a bridge",
348                         "operations": [
349                                 {
350                                         "httpMethod": "POST",
351                                         "summary": "Start a recording.",
352                                         "notes": "This records the mixed audio from all channels participating in this bridge.",
353                                         "nickname": "record",
354                                         "responseClass": "LiveRecording",
355                                         "parameters": [
356                                                 {
357                                                         "name": "bridgeId",
358                                                         "description": "Bridge's id",
359                                                         "paramType": "path",
360                                                         "required": true,
361                                                         "allowMultiple": false,
362                                                         "dataType": "string"
363                                                 },
364                                                 {
365                                                         "name": "name",
366                                                         "description": "Recording's filename",
367                                                         "paramType": "query",
368                                                         "required": true,
369                                                         "allowMultiple": false,
370                                                         "dataType": "string"
371                                                 },
372                                                 {
373                                                         "name": "format",
374                                                         "description": "Format to encode audio in",
375                                                         "paramType": "query",
376                                                         "required": true,
377                                                         "allowMultiple": false,
378                                                         "dataType": "string"
379                                                 },
380                                                 {
381                                                         "name": "maxDurationSeconds",
382                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit.",
383                                                         "paramType": "query",
384                                                         "required": false,
385                                                         "allowMultiple": false,
386                                                         "dataType": "int",
387                                                         "defaultValue": 0,
388                                                         "allowableValues": {
389                                                                 "valueType": "RANGE",
390                                                                 "min": 0
391                                                         }
392                                                 },
393                                                 {
394                                                         "name": "maxSilenceSeconds",
395                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit.",
396                                                         "paramType": "query",
397                                                         "required": false,
398                                                         "allowMultiple": false,
399                                                         "dataType": "int",
400                                                         "defaultValue": 0,
401                                                         "allowableValues": {
402                                                                 "valueType": "RANGE",
403                                                                 "min": 0
404                                                         }
405                                                 },
406                                                 {
407                                                         "name": "ifExists",
408                                                         "description": "Action to take if a recording with the same name already exists.",
409                                                         "paramType": "query",
410                                                         "required": false,
411                                                         "allowMultiple": false,
412                                                         "dataType": "string",
413                                                         "defaultValue": "fail",
414                                                         "allowableValues": {
415                                                                 "valueType": "LIST",
416                                                                 "values": [
417                                                                         "fail",
418                                                                         "overwrite",
419                                                                         "append"
420                                                                 ]
421                                                         }
422                                                 },
423                                                 {
424                                                         "name": "beep",
425                                                         "description": "Play beep when recording begins",
426                                                         "paramType": "query",
427                                                         "required": false,
428                                                         "allowMultiple": false,
429                                                         "dataType": "boolean",
430                                                         "defaultValue": false
431                                                 },
432                                                 {
433                                                         "name": "terminateOn",
434                                                         "description": "DTMF input to terminate recording.",
435                                                         "paramType": "query",
436                                                         "required": false,
437                                                         "allowMultiple": false,
438                                                         "dataType": "string",
439                                                         "defaultValue": "none",
440                                                         "allowableValues": {
441                                                                 "valueType": "LIST",
442                                                                 "values": [
443                                                                         "none",
444                                                                         "any",
445                                                                         "*",
446                                                                         "#"
447                                                                 ]
448                                                         }
449                                                 }
450                                         ],
451                     "errorResponses": [
452                         {
453                             "code": 400,
454                             "reason": "Invalid parameters"
455                         },
456                         {
457                             "code": 404,
458                             "reason": "Bridge not found"
459                         },
460                         {
461                             "code": 409,
462                             "reason": "Bridge is not in a Stasis application; A recording with the same name already exists on the system and can not be overwritten because it is in progress or ifExists=fail"
463                         },
464                                                 {
465                                                         "code": 422,
466                                                         "reason": "The format specified is unknown on this system"
467                                                 }
468                     ]
469                                 }
470                         ]
471                 }
472         ],
473         "models": {
474                 "Bridge": {
475                         "id": "Bridge",
476                         "description": "The merging of media from one or more channels.\n\nEveryone on the bridge receives the same audio.",
477                         "properties": {
478                                 "id": {
479                                         "type": "string",
480                                         "description": "Unique identifier for this bridge",
481                                         "required": true
482                                 },
483                                 "technology": {
484                                         "type": "string",
485                                         "description": "Name of the current bridging technology",
486                                         "required": true
487                                 },
488                                 "bridge_type": {
489                                         "type": "string",
490                                         "description": "Type of bridge technology",
491                                         "required": true,
492                                         "allowableValues": {
493                                                 "valueType": "LIST",
494                                                 "values": [
495                                                         "mixing",
496                                                         "holding"
497                                                 ]
498                                         }
499                                 },
500                                 "bridge_class": {
501                                         "type": "string",
502                                         "description": "Bridging class",
503                                         "required": true
504                                 },
505                                 "channels": {
506                                         "type": "List[string]",
507                                         "description": "Ids of channels participating in this bridge",
508                                         "required": true
509                                 }
510                         }
511                 }
512         }
513 }