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