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