rest-api/api-docs/asterisk.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": "2.0.0",
   6         "swaggerVersion": "1.1",
   7         "basePath": "http://localhost:8088/ari",
   8         "resourcePath": "/api-docs/asterisk.{format}",
   9         "apis": [
  10                 {
  11                         "path": "/asterisk/config/dynamic/{configClass}/{objectType}/{id}",
  12                         "description": "Asterisk dynamic configuration",
  13                         "operations": [
  14                                 {
  15                                         "httpMethod": "GET",
  16                                         "summary": "Retrieve a dynamic configuration object.",
  17                                         "nickname": "getObject",
  18                                         "responseClass": "List[ConfigTuple]",
  19                                         "parameters": [
  20                                                 {
  21                                                         "name": "configClass",
  22                                                         "description": "The configuration class containing dynamic configuration objects.",
  23                                                         "paramType": "path",
  24                                                         "required": true,
  25                                                         "allowMultiple": false,
  26                                                         "dataType": "string"
  27                                                 },
  28                                                 {
  29                                                         "name": "objectType",
  30                                                         "description": "The type of configuration object to retrieve.",
  31                                                         "paramType": "path",
  32                                                         "required": true,
  33                                                         "allowMultiple": false,
  34                                                         "dataType": "string"
  35                                                 },
  36                                                 {
  37                                                         "name": "id",
  38                                                         "description": "The unique identifier of the object to retrieve.",
  39                                                         "paramType": "path",
  40                                                         "required": true,
  41                                                         "allowMultiple": false,
  42                                                         "dataType": "string"
  43                                                 }
  44                                         ],
  45                                         "errorResponses": [
  46                                                 {
  47                                                         "code": 404,
  48                                                         "reason": "{configClass|objectType|id} not found"
  49                                                 }
  50                                         ]
  51                                 },
  52                                 {
  53                                         "httpMethod": "PUT",
  54                                         "summary": "Create or update a dynamic configuration object.",
  55                                         "nickname": "updateObject",
  56                                         "responseClass": "List[ConfigTuple]",
  57                                         "parameters": [
  58                                                 {
  59                                                         "name": "configClass",
  60                                                         "description": "The configuration class containing dynamic configuration objects.",
  61                                                         "paramType": "path",
  62                                                         "required": true,
  63                                                         "allowMultiple": false,
  64                                                         "dataType": "string"
  65                                                 },
  66                                                 {
  67                                                         "name": "objectType",
  68                                                         "description": "The type of configuration object to create or update.",
  69                                                         "paramType": "path",
  70                                                         "required": true,
  71                                                         "allowMultiple": false,
  72                                                         "dataType": "string"
  73                                                 },
  74                                                 {
  75                                                         "name": "id",
  76                                                         "description": "The unique identifier of the object to create or update.",
  77                                                         "paramType": "path",
  78                                                         "required": true,
  79                                                         "allowMultiple": false,
  80                                                         "dataType": "string"
  81                                                 },
  82                                                 {
  83                                                         "name": "fields",
  84                                                         "description": "The body object should have a value that is a list of ConfigTuples, which provide the fields to update. Ex. [ { \"attribute\": \"directmedia\", \"value\": \"false\" } ]",
  85                                                         "paramType": "body",
  86                                                         "required": false,
  87                                                         "dataType": "containers",
  88                                                         "allowMultiple": false
  89                                                 }
  90                                         ],
  91                                         "errorResponses": [
  92                                                 {
  93                                                         "code": 400,
  94                                                         "reason": "Bad request body"
  95                                                 },
  96                                                 {
  97                                                         "code": 403,
  98                                                         "reason": "Could not create or update object"
  99                                                 },
 100                                                 {
 101                                                         "code": 404,
 102                                                         "reason": "{configClass|objectType} not found"
 103                                                 }
 104                                         ]
 105                                 },
 106                                 {
 107                                         "httpMethod": "DELETE",
 108                                         "summary": "Delete a dynamic configuration object.",
 109                                         "nickname": "deleteObject",
 110                                         "responseClass": "void",
 111                                         "parameters": [
 112                                                 {
 113                                                         "name": "configClass",
 114                                                         "description": "The configuration class containing dynamic configuration objects.",
 115                                                         "paramType": "path",
 116                                                         "required": true,
 117                                                         "allowMultiple": false,
 118                                                         "dataType": "string"
 119                                                 },
 120                                                 {
 121                                                         "name": "objectType",
 122                                                         "description": "The type of configuration object to delete.",
 123                                                         "paramType": "path",
 124                                                         "required": true,
 125                                                         "allowMultiple": false,
 126                                                         "dataType": "string"
 127                                                 },
 128                                                 {
 129                                                         "name": "id",
 130                                                         "description": "The unique identifier of the object to delete.",
 131                                                         "paramType": "path",
 132                                                         "required": true,
 133                                                         "allowMultiple": false,
 134                                                         "dataType": "string"
 135                                                 }
 136                                         ],
 137                                         "errorResponses": [
 138                                                 {
 139                                                         "code": 403,
 140                                                         "reason": "Could not delete object"
 141                                                 },
 142                                                 {
 143                                                         "code": 404,
 144                                                         "reason": "{configClass|objectType|id} not found"
 145                                                 }
 146                                         ]
 147                                 }
 148                         ]
 149                 },
 150                 {
 151                         "path": "/asterisk/info",
 152                         "description": "Asterisk system information (similar to core show settings)",
 153                         "operations": [
 154                                 {
 155                                         "httpMethod": "GET",
 156                                         "summary": "Gets Asterisk system information.",
 157                                         "nickname": "getInfo",
 158                                         "responseClass": "AsteriskInfo",
 159                                         "parameters": [
 160                                                 {
 161                                                         "name": "only",
 162                                                         "description": "Filter information returned",
 163                                                         "paramType": "query",
 164                                                         "required": false,
 165                                                         "allowMultiple": true,
 166                                                         "dataType": "string",
 167                                                         "allowableValues": {
 168                                                                 "valueType": "LIST",
 169                                                                 "values": [
 170                                                                         "build",
 171                                                                         "system",
 172                                                                         "config",
 173                                                                         "status"
 174                                                                 ]
 175                                                         }
 176                                                 }
 177                                         ]
 178                                 }
 179                         ]
 180                 },
 181                 {
 182                         "path": "/asterisk/ping",
 183                         "description": "Asterisk ping",
 184                         "operations": [
 185                                 {
 186                                         "httpMethod": "GET",
 187                                         "summary": "Response pong message.",
 188                                         "nickname": "ping",
 189                                         "responseClass": "AsteriskPing"
 190                                 }
 191                         ]
 192                 },
 193                 {
 194                         "path": "/asterisk/modules",
 195                         "description": "Asterisk modules",
 196                         "operations": [
 197                                 {
 198                                         "httpMethod": "GET",
 199                                         "summary": "List Asterisk modules.",
 200                                         "nickname": "listModules",
 201                                         "responseClass": "List[Module]"
 202                                 }
 203                         ]
 204                 },
 205                 {
 206                         "path": "/asterisk/modules/{moduleName}",
 207                         "description": "Asterisk module",
 208                         "operations": [
 209                                 {
 210                                         "httpMethod": "GET",
 211                                         "summary": "Get Asterisk module information.",
 212                                         "nickname": "getModule",
 213                                         "responseClass": "Module",
 214                                         "parameters": [
 215                                                 {
 216                                                         "name": "moduleName",
 217                                                         "description": "Module's name",
 218                                                         "paramType": "path",
 219                                                         "required": true,
 220                                                         "allowMultiple": false,
 221                                                         "dataType": "string"
 222                                                 }
 223                                         ],
 224                                         "errorResponses": [
 225                                                 {
 226                                                         "code": 404,
 227                                                         "reason": "Module could not be found in running modules."
 228                                                 },
 229                                                 {
 230                                                         "code": 409,
 231                                                         "reason": "Module information could not be retrieved."
 232                                                 }
 233                                         ]
 234                                 },
 235                                 {
 236                                         "httpMethod": "POST",
 237                                         "summary": "Load an Asterisk module.",
 238                                         "nickname": "loadModule",
 239                                         "responseClass": "void",
 240                                         "parameters": [
 241                                                 {
 242                                                         "name": "moduleName",
 243                                                         "description": "Module's name",
 244                                                         "paramType": "path",
 245                                                         "required": true,
 246                                                         "allowMultiple": false,
 247                                                         "dataType": "string"
 248                                                 }
 249                                         ],
 250                                         "errorResponses": [
 251                                                 {
 252                                                         "code": 409,
 253                                                         "reason": "Module could not be loaded."
 254                                                 }
 255                                         ]
 256                                 },
 257                                 {
 258                                         "httpMethod": "DELETE",
 259                                         "summary": "Unload an Asterisk module.",
 260                                         "nickname": "unloadModule",
 261                                         "responseClass": "void",
 262                                         "parameters": [
 263                                                 {
 264                                                         "name": "moduleName",
 265                                                         "description": "Module's name",
 266                                                         "paramType": "path",
 267                                                         "required": true,
 268                                                         "allowMultiple": false,
 269                                                         "dataType": "string"
 270                                                 }
 271                                         ],
 272                                         "errorResponses": [
 273                                                 {
 274                                                         "code": 404,
 275                                                         "reason": "Module not found in running modules."
 276                                                 },
 277                                                 {
 278                                                         "code": 409,
 279                                                         "reason": "Module could not be unloaded."
 280                                                 }
 281                                         ]
 282                                 },
 283                                 {
 284                                         "httpMethod": "PUT",
 285                                         "summary": "Reload an Asterisk module.",
 286                                         "nickname": "reloadModule",
 287                                         "responseClass": "void",
 288                                         "parameters": [
 289                                                 {
 290                                                         "name": "moduleName",
 291                                                         "description": "Module's name",
 292                                                         "paramType": "path",
 293                                                         "required": true,
 294                                                         "allowMultiple": false,
 295                                                         "dataType": "string"
 296                                                 }
 297                                         ],
 298                                         "errorResponses": [
 299                                                 {
 300                                                         "code": 404,
 301                                                         "reason": "Module not found in running modules."
 302                                                 },
 303                                                 {
 304                                                         "code": 409,
 305                                                         "reason": "Module could not be reloaded."
 306                                                 }
 307                                         ]
 308                                 }
 309                         ]
 310                 },
 311                 {
 312                         "path": "/asterisk/logging",
 313                         "description": "Asterisk log channels",
 314                         "operations": [
 315                                 {
 316                                         "httpMethod": "GET",
 317                                         "summary": "Gets Asterisk log channel information.",
 318                                         "nickname": "listLogChannels",
 319                                         "responseClass": "List[LogChannel]"
 320                                 }
 321                         ]
 322                 },
 323                 {
 324                         "path": "/asterisk/logging/{logChannelName}",
 325                         "description": "Asterisk log channel",
 326                         "operations": [
 327                                 {
 328                                         "httpMethod": "POST",
 329                                         "summary": "Adds a log channel.",
 330                                         "nickname": "addLog",
 331                                         "responseClass": "void",
 332                                         "parameters": [
 333                                                 {
 334                                                         "name": "logChannelName",
 335                                                         "description": "The log channel to add",
 336                                                         "paramType": "path",
 337                                                         "required": true,
 338                                                         "allowMultiple": false,
 339                                                         "dataType": "string"
 340                                                 },
 341                                                 {
 342                                                         "name": "configuration",
 343                                                         "description": "levels of the log channel",
 344                                                         "paramType": "query",
 345                                                         "required": true,
 346                                                         "allowMultiple": false,
 347                                                         "dataType": "string"
 348                                                 }
 349                                         ],
 350                                         "errorResponses": [
 351                                                 {
 352                                                         "code": 400,
 353                                                         "reason": "Bad request body"
 354                                                 },
 355                                                 {
 356                                                         "code": 409,
 357                                                         "reason": "Log channel could not be created."
 358                                                 }
 359                                         ]
 360                                 },
 361                                 {
 362                                         "httpMethod": "DELETE",
 363                                         "summary": "Deletes a log channel.",
 364                                         "nickname": "deleteLog",
 365                                         "responseClass": "void",
 366                                         "parameters": [
 367                                                 {
 368                                                         "name": "logChannelName",
 369                                                         "description": "Log channels name",
 370                                                         "paramType": "path",
 371                                                         "required": true,
 372                                                         "allowMultiple": false,
 373                                                         "dataType": "string"
 374                                                 }
 375                                         ],
 376                                         "errorResponses": [
 377                                                 {
 378                                                         "code": 404,
 379                                                         "reason": "Log channel does not exist."
 380                                                 }
 381                                         ]
 382                                 }
 383                         ]
 384                 },
 385                 {
 386                         "path": "/asterisk/logging/{logChannelName}/rotate",
 387                         "description": "Asterisk log channel",
 388                         "operations": [
 389                                 {
 390                                         "httpMethod": "PUT",
 391                                         "summary": "Rotates a log channel.",
 392                                         "nickname": "rotateLog",
 393                                         "responseClass": "void",
 394                                         "parameters": [
 395                                                 {
 396                                                         "name": "logChannelName",
 397                                                         "description": "Log channel's name",
 398                                                         "paramType": "path",
 399                                                         "required": true,
 400                                                         "allowMultiple": false,
 401                                                         "dataType": "string"
 402                                                 }
 403                                         ],
 404                                         "errorResponses": [
 405                                                 {
 406                                                         "code": 404,
 407                                                         "reason": "Log channel does not exist."
 408                                                 }
 409                                         ]
 410                                 }
 411                         ]
 412                 },
 413                 {
 414                         "path": "/asterisk/variable",
 415                         "description": "Global variables",
 416                         "operations": [
 417                                 {
 418                                         "httpMethod": "GET",
 419                                         "summary": "Get the value of a global variable.",
 420                                         "nickname": "getGlobalVar",
 421                                         "responseClass": "Variable",
 422                                         "parameters": [
 423                                                 {
 424                                                         "name": "variable",
 425                                                         "description": "The variable to get",
 426                                                         "paramType": "query",
 427                                                         "required": true,
 428                                                         "allowMultiple": false,
 429                                                         "dataType": "string"
 430                                                 }
 431                                         ],
 432                                         "errorResponses": [
 433                                                 {
 434                                                         "code": 400,
 435                                                         "reason": "Missing variable parameter."
 436                                                 }
 437                                         ]
 438                                 },
 439                                 {
 440                                         "httpMethod": "POST",
 441                                         "summary": "Set the value of a global variable.",
 442                                         "nickname": "setGlobalVar",
 443                                         "responseClass": "void",
 444                                         "parameters": [
 445                                                 {
 446                                                         "name": "variable",
 447                                                         "description": "The variable to set",
 448                                                         "paramType": "query",
 449                                                         "required": true,
 450                                                         "allowMultiple": false,
 451                                                         "dataType": "string"
 452                                                 },
 453                                                 {
 454                                                         "name": "value",
 455                                                         "description": "The value to set the variable to",
 456                                                         "paramType": "query",
 457                                                         "required": false,
 458                                                         "allowMultiple": false,
 459                                                         "dataType": "string"
 460                                                 }
 461                                         ],
 462                                         "errorResponses": [
 463                                                 {
 464                                                         "code": 400,
 465                                                         "reason": "Missing variable parameter."
 466                                                 }
 467                                         ]
 468                                 }
 469                         ]
 470                 }
 471         ],
 472         "models": {
 473                 "BuildInfo": {
 474                         "id": "BuildInfo",
 475                         "description": "Info about how Asterisk was built",
 476                         "properties": {
 477                                 "os": {
 478                                         "required": true,
 479                                         "type": "string",
 480                                         "description": "OS Asterisk was built on."
 481                                 },
 482                                 "kernel": {
 483                                         "required": true,
 484                                         "type": "string",
 485                                         "description": "Kernel version Asterisk was built on."
 486                                 },
 487                                 "options": {
 488                                         "required": true,
 489                                         "type": "string",
 490                                         "description": "Compile time options, or empty string if default."
 491                                 },
 492                                 "machine": {
 493                                         "required": true,
 494                                         "type": "string",
 495                                         "description": "Machine architecture (x86_64, i686, ppc, etc.)"
 496                                 },
 497                                 "date": {
 498                                         "required": true,
 499                                         "type": "string",
 500                                         "description": "Date and time when Asterisk was built."
 501                                 },
 502                                 "user": {
 503                                         "required": true,
 504                                         "type": "string",
 505                                         "description": "Username that build Asterisk"
 506                                 }
 507                         }
 508                 },
 509                 "SystemInfo": {
 510                         "id": "SystemInfo",
 511                         "description": "Info about Asterisk",
 512                         "properties": {
 513                                 "version": {
 514                                         "required": true,
 515                                         "type": "string",
 516                                         "description": "Asterisk version."
 517                                 },
 518                                 "entity_id": {
 519                                         "required": true,
 520                                         "type": "string",
 521                                         "description": ""
 522                                 }
 523                         }
 524                 },
 525                 "SetId": {
 526                         "id": "SetId",
 527                         "description": "Effective user/group id",
 528                         "properties": {
 529                                 "user": {
 530                                         "required": true,
 531                                         "type": "string",
 532                                         "description": "Effective user id."
 533                                 },
 534                                 "group": {
 535                                         "required": true,
 536                                         "type": "string",
 537                                         "description": "Effective group id."
 538                                 }
 539                         }
 540                 },
 541                 "ConfigInfo": {
 542                         "id": "ConfigInfo",
 543                         "description": "Info about Asterisk configuration",
 544                         "properties": {
 545                                 "name": {
 546                                         "required": true,
 547                                         "type": "string",
 548                                         "description": "Asterisk system name."
 549                                 },
 550                                 "default_language": {
 551                                         "required": true,
 552                                         "type": "string",
 553                                         "description": "Default language for media playback."
 554                                 },
 555                                 "max_channels": {
 556                                         "required": false,
 557                                         "type": "int",
 558                                         "description": "Maximum number of simultaneous channels."
 559                                 },
 560                                 "max_open_files": {
 561                                         "required": false,
 562                                         "type": "int",
 563                                         "description": "Maximum number of open file handles (files, sockets)."
 564                                 },
 565                                 "max_load": {
 566                                         "required": false,
 567                                         "type": "double",
 568                                         "description": "Maximum load avg on system."
 569                                 },
 570                                 "setid": {
 571                                         "required": true,
 572                                         "type": "SetId",
 573                                         "description": "Effective user/group id for running Asterisk."
 574                                 }
 575                         }
 576                 },
 577                 "StatusInfo": {
 578                         "id": "StatusInfo",
 579                         "description": "Info about Asterisk status",
 580                         "properties": {
 581                                 "startup_time": {
 582                                         "required": true,
 583                                         "type": "Date",
 584                                         "description": "Time when Asterisk was started."
 585                                 },
 586                                 "last_reload_time": {
 587                                         "required": true,
 588                                         "type": "Date",
 589                                         "description": "Time when Asterisk was last reloaded."
 590                                 }
 591                         }
 592                 },
 593                 "AsteriskInfo": {
 594                         "id": "AsteriskInfo",
 595                         "description": "Asterisk system information",
 596                         "properties": {
 597                                 "build": {
 598                                         "required": false,
 599                                         "type": "BuildInfo",
 600                                         "description": "Info about how Asterisk was built"
 601                                 },
 602                                 "system": {
 603                                         "required": false,
 604                                         "type": "SystemInfo",
 605                                         "description": "Info about the system running Asterisk"
 606                                 },
 607                                 "config": {
 608                                         "required": false,
 609                                         "type": "ConfigInfo",
 610                                         "description": "Info about Asterisk configuration"
 611                                 },
 612                                 "status": {
 613                                         "required": false,
 614                                         "type": "StatusInfo",
 615                                         "description": "Info about Asterisk status"
 616                                 }
 617                         }
 618                 },
 619                 "AsteriskPing": {
 620                         "id": "AsteriskPing",
 621                         "description": "Asterisk ping information",
 622                         "properties": {
 623                                 "asterisk_id": {
 624                                         "required": true,
 625                                         "type": "string",
 626                                         "description": "Asterisk id info"
 627                                 },
 628                                 "ping": {
 629                                         "required": true,
 630                                         "type": "string",
 631                                         "description": "Always string value is pong"
 632                                 },
 633                                 "timestamp": {
 634                                         "required": true,
 635                                         "type": "string",
 636                                         "description": "The timestamp string of request received time"
 637                                 }
 638                         }
 639                 },
 640                 "Module": {
 641                         "id": "Module",
 642                         "description": "Details of an Asterisk module",
 643                         "properties": {
 644                                 "name": {
 645                                         "type": "string",
 646                                         "description": "The name of this module",
 647                                         "required": true
 648                                 },
 649                                 "description": {
 650                                         "type": "string",
 651                                         "description": "The description of this module",
 652                                         "required": true
 653                                 },
 654                                 "use_count": {
 655                                         "type": "int",
 656                                         "description": "The number of times this module is being used",
 657                                         "required": true
 658                                 },
 659                                 "status": {
 660                                         "type": "string",
 661                                         "description": "The running status of this module",
 662                                         "required": true
 663                                 },
 664                                 "support_level": {
 665                                         "type": "string",
 666                                         "description": "The support state of this module",
 667                                         "required": true
 668                                 }
 669                         }
 670                 },
 671                 "LogChannel": {
 672                         "id": "LogChannel",
 673                         "description": "Details of an Asterisk log channel",
 674                         "properties": {
 675                                 "channel": {
 676                                         "type": "string",
 677                                         "description": "The log channel path",
 678                                         "required": true
 679                                 },
 680                                 "type": {
 681                                         "type": "string",
 682                                         "description": "Types of logs for the log channel",
 683                                         "required": true
 684                                 },
 685                                 "status": {
 686                                         "type": "string",
 687                                         "description": "Whether or not a log type is enabled",
 688                                         "required": true
 689                                 },
 690                                 "configuration": {
 691                                         "type": "string",
 692                                         "description": "The various log levels",
 693                                         "required": true
 694                                 }
 695                         }
 696                 },
 697                 "Variable": {
 698                         "id": "Variable",
 699                         "description": "The value of a channel variable",
 700                         "properties": {
 701                                 "value": {
 702                                         "required": true,
 703                                         "type": "string",
 704                                         "description": "The value of the variable requested"
 705                                 }
 706                         }
 707                 },
 708                 "ConfigTuple": {
 709                         "id": "ConfigTuple",
 710                         "description": "A key/value pair that makes up part of a configuration object.",
 711                         "properties": {
 712                                 "attribute": {
 713                                         "required": true,
 714                                         "type": "string",
 715                                         "description": "A configuration object attribute."
 716                                 },
 717                                 "value": {
 718                                         "required": true,
 719                                         "type": "string",
 720                                         "description": "The value for the attribute."
 721                                 }
 722                         }
 723                 }
 724         }
 725 }