ari: Bump the version of ARI to 1.0.0
[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": "1.0.0",
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                                                         "name": "name",
44                                                         "description": "Name to give to the bridge being created.",
45                                                         "paramType": "query",
46                                                         "required": false,
47                                                         "allowMultiple": false,
48                                                         "dataType": "string"
49                                                 }
50                                         ]
51                                 }
52                         ]
53                 },
54                 {
55                         "path": "/bridges/{bridgeId}",
56                         "description": "Individual bridge",
57                         "operations": [
58                                 {
59                                         "httpMethod": "GET",
60                                         "summary": "Get bridge details.",
61                                         "nickname": "get",
62                                         "responseClass": "Bridge",
63                                         "parameters": [
64                                                 {
65                                                         "name": "bridgeId",
66                                                         "description": "Bridge's id",
67                                                         "paramType": "path",
68                                                         "required": true,
69                                                         "allowMultiple": false,
70                                                         "dataType": "string"
71                                                 }
72                                         ],
73                                         "errorResponses": [
74                                                 {
75                                                         "code": 404,
76                                                         "reason": "Bridge not found"
77                                                 }
78                                         ]
79                                 },
80                                 {
81                                         "httpMethod": "DELETE",
82                                         "summary": "Shut down a bridge.",
83                                         "notes": "If any channels are in this bridge, they will be removed and resume whatever they were doing beforehand.",
84                                         "nickname": "destroy",
85                                         "responseClass": "void",
86                                         "parameters": [
87                                                 {
88                                                         "name": "bridgeId",
89                                                         "description": "Bridge's id",
90                                                         "paramType": "path",
91                                                         "required": true,
92                                                         "allowMultiple": false,
93                                                         "dataType": "string"
94                                                 }
95                                         ],
96                                         "errorResponses": [
97                                                 {
98                                                         "code": 404,
99                                                         "reason": "Bridge not found"
100                                                 }
101                                         ]
102                                 }
103                         ]
104                 },
105                 {
106                         "path": "/bridges/{bridgeId}/addChannel",
107                         "description": "Add a channel to a bridge",
108                         "operations": [
109                                 {
110                                         "httpMethod": "POST",
111                                         "summary": "Add a channel to a bridge.",
112                                         "nickname": "addChannel",
113                                         "responseClass": "void",
114                                         "parameters": [
115                                                 {
116                                                         "name": "bridgeId",
117                                                         "description": "Bridge's id",
118                                                         "paramType": "path",
119                                                         "required": true,
120                                                         "allowMultiple": false,
121                                                         "dataType": "string"
122                                                 },
123                                                 {
124                                                         "name": "channel",
125                                                         "description": "Ids of channels to add to bridge",
126                                                         "paramType": "query",
127                                                         "required": true,
128                                                         "allowMultiple": true,
129                                                         "dataType": "string"
130                                                 },
131                                                 {
132                                                         "name": "role",
133                                                         "description": "Channel's role in the bridge",
134                                                         "paramType": "query",
135                                                         "required": false,
136                                                         "allowMultiple": false,
137                                                         "dataType": "string"
138                                                 }
139                                         ],
140                                         "errorResponses": [
141                                                 {
142                                                         "code": 400,
143                                                         "reason": "Channel not found"
144                                                 },
145                                                 {
146                                                         "code": 404,
147                                                         "reason": "Bridge not found"
148                                                 },
149                                                 {
150                                                         "code": 409,
151                                                         "reason": "Bridge not in Stasis application; Channel currently recording"
152                                                 },
153                                                 {
154                                                         "code": 422,
155                                                         "reason": "Channel not in Stasis application"
156                                                 }
157                                         ]
158                                 }
159                         ]
160                 },
161                 {
162                         "path": "/bridges/{bridgeId}/removeChannel",
163                         "description": "Remove a channel from a bridge",
164                         "operations": [
165                                 {
166                                         "httpMethod": "POST",
167                                         "summary": "Remove a channel from a bridge.",
168                                         "nickname": "removeChannel",
169                                         "responseClass": "void",
170                                         "parameters": [
171                                                 {
172                                                         "name": "bridgeId",
173                                                         "description": "Bridge's id",
174                                                         "paramType": "path",
175                                                         "required": true,
176                                                         "allowMultiple": false,
177                                                         "dataType": "string"
178                                                 },
179                                                 {
180                                                         "name": "channel",
181                                                         "description": "Ids of channels to remove from bridge",
182                                                         "paramType": "query",
183                                                         "required": true,
184                                                         "allowMultiple": true,
185                                                         "dataType": "string"
186                                                 }
187                                         ],
188                                         "errorResponses": [
189                                                 {
190                                                         "code": 400,
191                                                         "reason": "Channel not found"
192                                                 },
193                                                 {
194                                                         "code": 404,
195                                                         "reason": "Bridge not found"
196                                                 },
197                                                 {
198                                                         "code": 409,
199                                                         "reason": "Bridge not in Stasis application"
200                                                 },
201                                                 {
202                                                         "code": 422,
203                                                         "reason": "Channel not in this bridge"
204                                                 }
205                                         ]
206                                 }
207                         ]
208                 },
209                 {
210                         "path": "/bridges/{bridgeId}/moh",
211                         "description": "Play music on hold to a bridge",
212                         "operations": [
213                                 {
214                                         "httpMethod": "POST",
215                                         "summary": "Play music on hold to a bridge or change the MOH class that is playing.",
216                                         "nickname": "startMoh",
217                                         "responseClass": "void",
218                                         "parameters": [
219                                                 {
220                                                         "name": "bridgeId",
221                                                         "description": "Bridge's id",
222                                                         "paramType": "path",
223                                                         "required": true,
224                                                         "allowMultiple": false,
225                                                         "dataType": "string"
226                                                 },
227                                                 {
228                                                         "name": "mohClass",
229                                                         "description": "Channel's id",
230                                                         "paramType": "query",
231                                                         "required": false,
232                                                         "allowMultiple": false,
233                                                         "dataType": "string"
234                                                 }
235                                         ],
236                                         "errorResponses": [
237                                                 {
238                                                         "code": 404,
239                                                         "reason": "Bridge not found"
240                                                 },
241                                                 {
242                                                         "code": 409,
243                                                         "reason": "Bridge not in Stasis application"
244                                                 }
245                                         ]
246                                 },
247                                 {
248                                         "httpMethod": "DELETE",
249                                         "summary": "Stop playing music on hold to a bridge.",
250                                         "notes": "This will only stop music on hold being played via POST bridges/{bridgeId}/moh.",
251                                         "nickname": "stopMoh",
252                                         "responseClass": "void",
253                                         "parameters": [
254                                                 {
255                                                         "name": "bridgeId",
256                                                         "description": "Bridge's id",
257                                                         "paramType": "path",
258                                                         "required": true,
259                                                         "allowMultiple": false,
260                                                         "dataType": "string"
261                                                 }
262                                         ],
263                                         "errorResponses": [
264                                                 {
265                                                         "code": 404,
266                                                         "reason": "Bridge not found"
267                                                 },
268                                                 {
269                                                         "code": 409,
270                                                         "reason": "Bridge not in Stasis application"
271                                                 }
272                                         ]
273                                 }
274                         ]
275                 },
276                 {
277                         "path": "/bridges/{bridgeId}/play",
278                         "description": "Play media to the participants of a bridge",
279                         "operations": [
280                                 {
281                                         "httpMethod": "POST",
282                                         "summary": "Start playback of media on a bridge.",
283                                         "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.)",
284                                         "nickname": "play",
285                                         "responseClass": "Playback",
286                                         "parameters": [
287                                                 {
288                                                         "name": "bridgeId",
289                                                         "description": "Bridge's id",
290                                                         "paramType": "path",
291                                                         "required": true,
292                                                         "allowMultiple": false,
293                                                         "dataType": "string"
294                                                 },
295                                                 {
296                                                         "name": "media",
297                                                         "description": "Media's URI to play.",
298                                                         "paramType": "query",
299                                                         "required": true,
300                                                         "allowMultiple": false,
301                                                         "dataType": "string"
302                                                 },
303                                                 {
304                                                         "name": "lang",
305                                                         "description": "For sounds, selects language for sound.",
306                                                         "paramType": "query",
307                                                         "required": false,
308                                                         "allowMultiple": false,
309                                                         "dataType": "string"
310                                                 },
311                                                 {
312                                                         "name": "offsetms",
313                                                         "description": "Number of media to skip before playing.",
314                                                         "paramType": "query",
315                                                         "required": false,
316                                                         "allowMultiple": false,
317                                                         "dataType": "int",
318                                                         "defaultValue": 0,
319                                                         "allowableValues": {
320                                                                 "valueType": "RANGE",
321                                                                 "min": 0
322                                                         }
323
324                                                 },
325                                                 {
326                                                         "name": "skipms",
327                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
328                                                         "paramType": "query",
329                                                         "required": false,
330                                                         "allowMultiple": false,
331                                                         "dataType": "int",
332                                                         "defaultValue": 3000,
333                                                         "allowableValues": {
334                                                                 "valueType": "RANGE",
335                                                                 "min": 0
336                                                         }
337
338                                                 }
339                                         ],
340                                         "errorResponses": [
341                                                 {
342                                                         "code": 404,
343                                                         "reason": "Bridge not found"
344                                                 },
345                                                 {
346                                                         "code": 409,
347                                                         "reason": "Bridge not in a Stasis application"
348                                                 }
349                                         ]
350                                 }
351                         ]
352                 },
353                 {
354                         "path": "/bridges/{bridgeId}/record",
355                         "description": "Record audio on a bridge",
356                         "operations": [
357                                 {
358                                         "httpMethod": "POST",
359                                         "summary": "Start a recording.",
360                                         "notes": "This records the mixed audio from all channels participating in this bridge.",
361                                         "nickname": "record",
362                                         "responseClass": "LiveRecording",
363                                         "parameters": [
364                                                 {
365                                                         "name": "bridgeId",
366                                                         "description": "Bridge's id",
367                                                         "paramType": "path",
368                                                         "required": true,
369                                                         "allowMultiple": false,
370                                                         "dataType": "string"
371                                                 },
372                                                 {
373                                                         "name": "name",
374                                                         "description": "Recording's filename",
375                                                         "paramType": "query",
376                                                         "required": true,
377                                                         "allowMultiple": false,
378                                                         "dataType": "string"
379                                                 },
380                                                 {
381                                                         "name": "format",
382                                                         "description": "Format to encode audio in",
383                                                         "paramType": "query",
384                                                         "required": true,
385                                                         "allowMultiple": false,
386                                                         "dataType": "string"
387                                                 },
388                                                 {
389                                                         "name": "maxDurationSeconds",
390                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit.",
391                                                         "paramType": "query",
392                                                         "required": false,
393                                                         "allowMultiple": false,
394                                                         "dataType": "int",
395                                                         "defaultValue": 0,
396                                                         "allowableValues": {
397                                                                 "valueType": "RANGE",
398                                                                 "min": 0
399                                                         }
400                                                 },
401                                                 {
402                                                         "name": "maxSilenceSeconds",
403                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit.",
404                                                         "paramType": "query",
405                                                         "required": false,
406                                                         "allowMultiple": false,
407                                                         "dataType": "int",
408                                                         "defaultValue": 0,
409                                                         "allowableValues": {
410                                                                 "valueType": "RANGE",
411                                                                 "min": 0
412                                                         }
413                                                 },
414                                                 {
415                                                         "name": "ifExists",
416                                                         "description": "Action to take if a recording with the same name already exists.",
417                                                         "paramType": "query",
418                                                         "required": false,
419                                                         "allowMultiple": false,
420                                                         "dataType": "string",
421                                                         "defaultValue": "fail",
422                                                         "allowableValues": {
423                                                                 "valueType": "LIST",
424                                                                 "values": [
425                                                                         "fail",
426                                                                         "overwrite",
427                                                                         "append"
428                                                                 ]
429                                                         }
430                                                 },
431                                                 {
432                                                         "name": "beep",
433                                                         "description": "Play beep when recording begins",
434                                                         "paramType": "query",
435                                                         "required": false,
436                                                         "allowMultiple": false,
437                                                         "dataType": "boolean",
438                                                         "defaultValue": false
439                                                 },
440                                                 {
441                                                         "name": "terminateOn",
442                                                         "description": "DTMF input to terminate recording.",
443                                                         "paramType": "query",
444                                                         "required": false,
445                                                         "allowMultiple": false,
446                                                         "dataType": "string",
447                                                         "defaultValue": "none",
448                                                         "allowableValues": {
449                                                                 "valueType": "LIST",
450                                                                 "values": [
451                                                                         "none",
452                                                                         "any",
453                                                                         "*",
454                                                                         "#"
455                                                                 ]
456                                                         }
457                                                 }
458                                         ],
459                     "errorResponses": [
460                         {
461                             "code": 400,
462                             "reason": "Invalid parameters"
463                         },
464                         {
465                             "code": 404,
466                             "reason": "Bridge not found"
467                         },
468                         {
469                             "code": 409,
470                             "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"
471                         },
472                                                 {
473                                                         "code": 422,
474                                                         "reason": "The format specified is unknown on this system"
475                                                 }
476                     ]
477                                 }
478                         ]
479                 }
480         ],
481         "models": {
482                 "Bridge": {
483                         "id": "Bridge",
484                         "description": "The merging of media from one or more channels.\n\nEveryone on the bridge receives the same audio.",
485                         "properties": {
486                                 "id": {
487                                         "type": "string",
488                                         "description": "Unique identifier for this bridge",
489                                         "required": true
490                                 },
491                                 "technology": {
492                                         "type": "string",
493                                         "description": "Name of the current bridging technology",
494                                         "required": true
495                                 },
496                                 "bridge_type": {
497                                         "type": "string",
498                                         "description": "Type of bridge technology",
499                                         "required": true,
500                                         "allowableValues": {
501                                                 "valueType": "LIST",
502                                                 "values": [
503                                                         "mixing",
504                                                         "holding"
505                                                 ]
506                                         }
507                                 },
508                                 "bridge_class": {
509                                         "type": "string",
510                                         "description": "Bridging class",
511                                         "required": true
512                                 },
513                                 "creator": {
514                                         "type": "string",
515                                         "description": "Entity that created the bridge",
516                                         "required": true
517                                 },
518                                 "name": {
519                                         "type": "string",
520                                         "description": "Name the creator gave the bridge",
521                                         "required": true
522                                 },
523                                 "channels": {
524                                         "type": "List[string]",
525                                         "description": "Ids of channels participating in this bridge",
526                                         "required": true
527                                 }
528                         }
529                 }
530         }
531 }