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 all active bridges in Asterisk.",
  17                                         "nickname": "list",
  18                                         "responseClass": "List[Bridge]"
  19                                 },
  20                                 {
  21                                         "httpMethod": "POST",
  22                                         "summary": "Create a new bridge.",
  23                                         "notes": "This bridge persists until it has been shut down, or Asterisk has been shut down.",
  24                                         "nickname": "create",
  25                                         "responseClass": "Bridge",
  26                                         "parameters": [
  27                                                 {
  28                                                         "name": "type",
  29                                                         "description": "Type of bridge to create.",
  30                                                         "paramType": "query",
  31                                                         "required": false,
  32                                                         "allowMultiple": false,
  33                                                         "dataType": "string",
  34                                                         "allowableValues": {
  35                                                                 "valueType": "LIST",
  36                                                                 "values": [
  37                                                                         "mixing",
  38                                                                         "holding"
  39                                                                 ]
  40                                                         }
  41                                                 }
  42                                         ]
  43                                 }
  44                         ]
  45                 },
  46                 {
  47                         "path": "/bridges/{bridgeId}",
  48                         "description": "Individual bridge",
  49                         "operations": [
  50                                 {
  51                                         "httpMethod": "GET",
  52                                         "summary": "Get bridge details.",
  53                                         "nickname": "get",
  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": "destroy",
  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": "addChannel",
 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; Channel currently recording"
 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": "removeChannel",
 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}/moh",
 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": "startMoh",
 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                                         "httpMethod": "DELETE",
 241                                         "summary": "Stop playing music on hold to a bridge.",
 242                                         "notes": "This will only stop music on hold being played via POST bridges/{bridgeId}/moh.",
 243                                         "nickname": "stopMoh",
 244                                         "responseClass": "void",
 245                                         "parameters": [
 246                                                 {
 247                                                         "name": "bridgeId",
 248                                                         "description": "Bridge's id",
 249                                                         "paramType": "path",
 250                                                         "required": true,
 251                                                         "allowMultiple": false,
 252                                                         "dataType": "string"
 253                                                 }
 254                                         ],
 255                                         "errorResponses": [
 256                                                 {
 257                                                         "code": 404,
 258                                                         "reason": "Bridge not found"
 259                                                 },
 260                                                 {
 261                                                         "code": 409,
 262                                                         "reason": "Bridge not in Stasis application"
 263                                                 }
 264                                         ]
 265                                 }
 266                         ]
 267                 },
 268                 {
 269                         "path": "/bridges/{bridgeId}/play",
 270                         "description": "Play media to the participants of a bridge",
 271                         "operations": [
 272                                 {
 273                                         "httpMethod": "POST",
 274                                         "summary": "Start playback of media on a bridge.",
 275                                         "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.)",
 276                                         "nickname": "play",
 277                                         "responseClass": "Playback",
 278                                         "parameters": [
 279                                                 {
 280                                                         "name": "bridgeId",
 281                                                         "description": "Bridge's id",
 282                                                         "paramType": "path",
 283                                                         "required": true,
 284                                                         "allowMultiple": false,
 285                                                         "dataType": "string"
 286                                                 },
 287                                                 {
 288                                                         "name": "media",
 289                                                         "description": "Media's URI to play.",
 290                                                         "paramType": "query",
 291                                                         "required": true,
 292                                                         "allowMultiple": false,
 293                                                         "dataType": "string"
 294                                                 },
 295                                                 {
 296                                                         "name": "lang",
 297                                                         "description": "For sounds, selects language for sound.",
 298                                                         "paramType": "query",
 299                                                         "required": false,
 300                                                         "allowMultiple": false,
 301                                                         "dataType": "string"
 302                                                 },
 303                                                 {
 304                                                         "name": "offsetms",
 305                                                         "description": "Number of media to skip before playing.",
 306                                                         "paramType": "query",
 307                                                         "required": false,
 308                                                         "allowMultiple": false,
 309                                                         "dataType": "int",
 310                                                         "defaultValue": 0,
 311                                                         "allowableValues": {
 312                                                                 "valueType": "RANGE",
 313                                                                 "min": 0
 314                                                         }
 315
 316                                                 },
 317                                                 {
 318                                                         "name": "skipms",
 319                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
 320                                                         "paramType": "query",
 321                                                         "required": false,
 322                                                         "allowMultiple": false,
 323                                                         "dataType": "int",
 324                                                         "defaultValue": 3000,
 325                                                         "allowableValues": {
 326                                                                 "valueType": "RANGE",
 327                                                                 "min": 0
 328                                                         }
 329
 330                                                 }
 331                                         ],
 332                                         "errorResponses": [
 333                                                 {
 334                                                         "code": 404,
 335                                                         "reason": "Bridge not found"
 336                                                 },
 337                                                 {
 338                                                         "code": 409,
 339                                                         "reason": "Bridge not in a Stasis application"
 340                                                 }
 341                                         ]
 342                                 }
 343                         ]
 344                 },
 345                 {
 346                         "path": "/bridges/{bridgeId}/record",
 347                         "description": "Record audio on a bridge",
 348                         "operations": [
 349                                 {
 350                                         "httpMethod": "POST",
 351                                         "summary": "Start a recording.",
 352                                         "notes": "This records the mixed audio from all channels participating in this bridge.",
 353                                         "nickname": "record",
 354                                         "responseClass": "LiveRecording",
 355                                         "parameters": [
 356                                                 {
 357                                                         "name": "bridgeId",
 358                                                         "description": "Bridge's id",
 359                                                         "paramType": "path",
 360                                                         "required": true,
 361                                                         "allowMultiple": false,
 362                                                         "dataType": "string"
 363                                                 },
 364                                                 {
 365                                                         "name": "name",
 366                                                         "description": "Recording's filename",
 367                                                         "paramType": "query",
 368                                                         "required": true,
 369                                                         "allowMultiple": false,
 370                                                         "dataType": "string"
 371                                                 },
 372                                                 {
 373                                                         "name": "format",
 374                                                         "description": "Format to encode audio in",
 375                                                         "paramType": "query",
 376                                                         "required": true,
 377                                                         "allowMultiple": false,
 378                                                         "dataType": "string"
 379                                                 },
 380                                                 {
 381                                                         "name": "maxDurationSeconds",
 382                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit.",
 383                                                         "paramType": "query",
 384                                                         "required": false,
 385                                                         "allowMultiple": false,
 386                                                         "dataType": "int",
 387                                                         "defaultValue": 0,
 388                                                         "allowableValues": {
 389                                                                 "valueType": "RANGE",
 390                                                                 "min": 0
 391                                                         }
 392                                                 },
 393                                                 {
 394                                                         "name": "maxSilenceSeconds",
 395                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit.",
 396                                                         "paramType": "query",
 397                                                         "required": false,
 398                                                         "allowMultiple": false,
 399                                                         "dataType": "int",
 400                                                         "defaultValue": 0,
 401                                                         "allowableValues": {
 402                                                                 "valueType": "RANGE",
 403                                                                 "min": 0
 404                                                         }
 405                                                 },
 406                                                 {
 407                                                         "name": "ifExists",
 408                                                         "description": "Action to take if a recording with the same name already exists.",
 409                                                         "paramType": "query",
 410                                                         "required": false,
 411                                                         "allowMultiple": false,
 412                                                         "dataType": "string",
 413                                                         "defaultValue": "fail",
 414                                                         "allowableValues": {
 415                                                                 "valueType": "LIST",
 416                                                                 "values": [
 417                                                                         "fail",
 418                                                                         "overwrite",
 419                                                                         "append"
 420                                                                 ]
 421                                                         }
 422                                                 },
 423                                                 {
 424                                                         "name": "beep",
 425                                                         "description": "Play beep when recording begins",
 426                                                         "paramType": "query",
 427                                                         "required": false,
 428                                                         "allowMultiple": false,
 429                                                         "dataType": "boolean",
 430                                                         "defaultValue": false
 431                                                 },
 432                                                 {
 433                                                         "name": "terminateOn",
 434                                                         "description": "DTMF input to terminate recording.",
 435                                                         "paramType": "query",
 436                                                         "required": false,
 437                                                         "allowMultiple": false,
 438                                                         "dataType": "string",
 439                                                         "defaultValue": "none",
 440                                                         "allowableValues": {
 441                                                                 "valueType": "LIST",
 442                                                                 "values": [
 443                                                                         "none",
 444                                                                         "any",
 445                                                                         "*",
 446                                                                         "#"
 447                                                                 ]
 448                                                         }
 449                                                 }
 450                                         ],
 451                     "errorResponses": [
 452                         {
 453                             "code": 400,
 454                             "reason": "Invalid parameters"
 455                         },
 456                         {
 457                             "code": 404,
 458                             "reason": "Bridge not found"
 459                         },
 460                         {
 461                             "code": 409,
 462                             "reason": "Bridge is not in a Stasis application; A recording with the same name already exists on the system and can not be overwritten because it is in progress or ifExists=fail"
 463                         },
 464                                                 {
 465                                                         "code": 422,
 466                                                         "reason": "The format specified is unknown on this system"
 467                                                 }
 468                     ]
 469                                 }
 470                         ]
 471                 }
 472         ],
 473         "models": {
 474                 "Bridge": {
 475                         "id": "Bridge",
 476                         "description": "The merging of media from one or more channels.\n\nEveryone on the bridge receives the same audio.",
 477                         "properties": {
 478                                 "id": {
 479                                         "type": "string",
 480                                         "description": "Unique identifier for this bridge",
 481                                         "required": true
 482                                 },
 483                                 "technology": {
 484                                         "type": "string",
 485                                         "description": "Name of the current bridging technology",
 486                                         "required": true
 487                                 },
 488                                 "bridge_type": {
 489                                         "type": "string",
 490                                         "description": "Type of bridge technology",
 491                                         "required": true,
 492                                         "allowableValues": {
 493                                                 "valueType": "LIST",
 494                                                 "values": [
 495                                                         "mixing",
 496                                                         "holding"
 497                                                 ]
 498                                         }
 499                                 },
 500                                 "bridge_class": {
 501                                         "type": "string",
 502                                         "description": "Bridging class",
 503                                         "required": true
 504                                 },
 505                                 "channels": {
 506                                         "type": "List[string]",
 507                                         "description": "Ids of channels participating in this bridge",
 508                                         "required": true
 509                                 }
 510                         }
 511                 }
 512         }
 513 }