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