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