7b3c4a37b9140ea68911dadb02144a7dac020229
[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": "Channel's id",
118                                                         "paramType": "query",
119                                                         "required": true,
120                                                         "allowMultiple": true,
121                                                         "dataType": "string"
122                                                 }
123                                         ],
124                                         "errorResponses": [
125                                                 {
126                                                         "code": 404,
127                                                         "reason": "Bridge not found"
128                                                 },
129                                                 {
130                                                         "code": 409,
131                                                         "reason": "Bridge not in Stasis application"
132                                                 },
133                                                 {
134                                                         "code": 422,
135                                                         "reason": "Channel not found, or not in Stasis application"
136                                                 }
137                                         ]
138                                 }
139                         ]
140                 },
141                 {
142                         "path": "/bridges/{bridgeId}/removeChannel",
143                         "description": "Remove a channel from a bridge",
144                         "operations": [
145                                 {
146                                         "httpMethod": "POST",
147                                         "summary": "Remove a channel from a bridge.",
148                                         "nickname": "removeChannelFromBridge",
149                                         "responseClass": "void",
150                                         "parameters": [
151                                                 {
152                                                         "name": "bridgeId",
153                                                         "description": "Bridge's id",
154                                                         "paramType": "path",
155                                                         "required": true,
156                                                         "allowMultiple": false,
157                                                         "dataType": "string"
158                                                 },
159                                                 {
160                                                         "name": "channel",
161                                                         "description": "Channel's id",
162                                                         "paramType": "query",
163                                                         "required": true,
164                                                         "allowMultiple": true,
165                                                         "dataType": "string"
166                                                 }
167                                         ]
168                                 }
169                         ]
170                 },
171                 {
172                         "path": "/bridges/{bridgeId}/play",
173                         "description": "Play media to the participants of a bridge",
174                         "operations": [
175                                 {
176                                         "httpMethod": "POST",
177                                         "summary": "Start playback of media on a bridge.",
178                                         "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.)",
179                                         "nickname": "playOnBridge",
180                                         "responseClass": "Playback",
181                                         "parameters": [
182                                                 {
183                                                         "name": "bridgeId",
184                                                         "description": "Bridge's id",
185                                                         "paramType": "path",
186                                                         "required": true,
187                                                         "allowMultiple": false,
188                                                         "dataType": "string"
189                                                 },
190                                                 {
191                                                         "name": "media",
192                                                         "description": "Media's URI to play.",
193                                                         "paramType": "query",
194                                                         "required": true,
195                                                         "allowMultiple": false,
196                                                         "dataType": "string"
197                                                 },
198                                                 {
199                                                         "name": "lang",
200                                                         "description": "For sounds, selects language for sound.",
201                                                         "paramType": "query",
202                                                         "required": false,
203                                                         "allowMultiple": false,
204                                                         "dataType": "string"
205                                                 },
206                                                 {
207                                                         "name": "offsetms",
208                                                         "description": "Number of media to skip before playing.",
209                                                         "paramType": "query",
210                                                         "required": false,
211                                                         "allowMultiple": false,
212                                                         "dataType": "int",
213                                                         "defaultValue": 0,
214                                                         "allowableValues": {
215                                                                 "valueType": "RANGE",
216                                                                 "min": 0
217                                                         }
218
219                                                 },
220                                                 {
221                                                         "name": "skipms",
222                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
223                                                         "paramType": "query",
224                                                         "required": false,
225                                                         "allowMultiple": false,
226                                                         "dataType": "int",
227                                                         "defaultValue": 3000,
228                                                         "allowableValues": {
229                                                                 "valueType": "RANGE",
230                                                                 "min": 0
231                                                         }
232
233                                                 }
234                                         ],
235                                         "errorResponses": [
236                                                 {
237                                                         "code": 404,
238                                                         "reason": "Bridge not found"
239                                                 },
240                                                 {
241                                                         "code": 409,
242                                                         "reason": "Bridge not in a Stasis application"
243                                                 }
244                                         ]
245                                 }
246                         ]
247                 },
248                 {
249                         "path": "/bridges/{bridgeId}/record",
250                         "description": "Record audio on a bridge",
251                         "operations": [
252                                 {
253                                         "httpMethod": "POST",
254                                         "summary": "Start a recording.",
255                                         "notes": "This records the mixed audio from all channels participating in this bridge.",
256                                         "nickname": "recordBridge",
257                                         "responseClass": "LiveRecording",
258                                         "parameters": [
259                                                 {
260                                                         "name": "bridgeId",
261                                                         "description": "Bridge's id",
262                                                         "paramType": "path",
263                                                         "required": true,
264                                                         "allowMultiple": false,
265                                                         "dataType": "string"
266                                                 },
267                                                 {
268                                                         "name": "name",
269                                                         "description": "Recording's filename",
270                                                         "paramType": "query",
271                                                         "required": true,
272                                                         "allowMultiple": false,
273                                                         "dataType": "string"
274                                                 },
275                                                 {
276                                                         "name": "format",
277                                                         "description": "Format to encode audio in",
278                                                         "paramType": "query",
279                                                         "required": true,
280                                                         "allowMultiple": true,
281                                                         "dataType": "string"
282                                                 },
283                                                 {
284                                                         "name": "maxDurationSeconds",
285                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit.",
286                                                         "paramType": "query",
287                                                         "required": false,
288                                                         "allowMultiple": false,
289                                                         "dataType": "int",
290                                                         "defaultValue": 0,
291                                                         "allowableValues": {
292                                                                 "valueType": "RANGE",
293                                                                 "min": 0
294                                                         }
295                                                 },
296                                                 {
297                                                         "name": "maxSilenceSeconds",
298                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit.",
299                                                         "paramType": "query",
300                                                         "required": false,
301                                                         "allowMultiple": false,
302                                                         "dataType": "int",
303                                                         "defaultValue": 0,
304                                                         "allowableValues": {
305                                                                 "valueType": "RANGE",
306                                                                 "min": 0
307                                                         }
308                                                 },
309                                                 {
310                                                         "name": "ifExists",
311                                                         "description": "Action to take if a recording with the same name already exists.",
312                                                         "paramType": "query",
313                                                         "required": false,
314                                                         "allowMultiple": false,
315                                                         "dataType": "string",
316                                                         "defaultValue": "fail",
317                                                         "allowableValues": {
318                                                                 "valueType": "LIST",
319                                                                 "values": [
320                                                                         "fail",
321                                                                         "overwrite",
322                                                                         "append"
323                                                                 ]
324                                                         }
325                                                 },
326                                                 {
327                                                         "name": "beep",
328                                                         "description": "Play beep when recording begins",
329                                                         "paramType": "query",
330                                                         "required": false,
331                                                         "allowMultiple": false,
332                                                         "dataType": "boolean",
333                                                         "defaultValue": false
334                                                 },
335                                                 {
336                                                         "name": "terminateOn",
337                                                         "description": "DTMF input to terminate recording.",
338                                                         "paramType": "query",
339                                                         "required": false,
340                                                         "allowMultiple": false,
341                                                         "dataType": "string",
342                                                         "defaultValue": "none",
343                                                         "allowableValues": {
344                                                                 "valueType": "LIST",
345                                                                 "values": [
346                                                                         "none",
347                                                                         "any",
348                                                                         "*",
349                                                                         "#"
350                                                                 ]
351                                                         }
352                                                 }
353                                         ]
354                                 }
355                         ]
356                 }
357         ],
358         "models": {
359                 "Bridge": {
360                         "id": "Bridge",
361                         "description": "The merging of media from one or more channels.\n\nEveryone on the bridge receives the same audio.",
362                         "properties": {
363                                 "id": {
364                                         "type": "string",
365                                         "description": "Unique identifier for this bridge",
366                                         "required": true
367                                 },
368                                 "technology": {
369                                         "type": "string",
370                                         "description": "Name of the current bridging technology",
371                                         "required": true
372                                 },
373                                 "bridge_type": {
374                                         "type": "string",
375                                         "description": "Type of bridge technology",
376                                         "required": true,
377                                         "allowableValues": {
378                                                 "valueType": "LIST",
379                                                 "values": [
380                                                         "mixing",
381                                                         "holding"
382                                                 ]
383                                         }
384                                 },
385                                 "bridge_class": {
386                                         "type": "string",
387                                         "description": "Bridging class",
388                                         "required": true
389                                 },
390                                 "channels": {
391                                         "type": "List[string]",
392                                         "description": "Id's of channels participating in this bridge",
393                                         "required": true
394                                 }
395                         }
396                 }
397         }
398 }