Merge "bridging: Add better support for adding/removing streams."
[asterisk/asterisk.git] / 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 }