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