2705f45f65b3577a4c08281c5d17813071d543b8
[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": "1.7.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/modules",
183                         "description": "Asterisk modules",
184                         "operations": [
185                                 {
186                                         "httpMethod": "GET",
187                                         "summary": "List Asterisk modules.",
188                                         "nickname": "listModules",
189                                         "responseClass": "List[Module]"
190                                 }
191                         ]
192                 },
193                 {
194                         "path": "/asterisk/modules/{moduleName}",
195                         "description": "Asterisk module",
196                         "operations": [
197                                 {
198                                         "httpMethod": "GET",
199                                         "summary": "Get Asterisk module information.",
200                                         "nickname": "getModule",
201                                         "responseClass": "Module",
202                                         "parameters": [
203                                                 {
204                                                         "name": "moduleName",
205                                                         "description": "Module's name",
206                                                         "paramType": "path",
207                                                         "required": true,
208                                                         "allowMultiple": false,
209                                                         "dataType": "string"
210                                                 }
211                                         ],
212                                         "errorResponses": [
213                                                 {
214                                                         "code": 404,
215                                                         "reason": "Module could not be found in running modules."
216                                                 },
217                                                 {
218                                                         "code": 409,
219                                                         "reason": "Module information could not be retrieved."
220                                                 }
221                                         ]
222                                 },
223                                 {
224                                         "httpMethod": "POST",
225                                         "summary": "Load an Asterisk module.",
226                                         "nickname": "loadModule",
227                                         "responseClass": "void",
228                                         "parameters": [
229                                                 {
230                                                         "name": "moduleName",
231                                                         "description": "Module's name",
232                                                         "paramType": "path",
233                                                         "required": true,
234                                                         "allowMultiple": false,
235                                                         "dataType": "string"
236                                                 }
237                                         ],
238                                         "errorResponses": [
239                                                 {
240                                                         "code": 409,
241                                                         "reason": "Module could not be loaded."
242                                                 }
243                                         ]
244                                 },
245                                 {
246                                         "httpMethod": "DELETE",
247                                         "summary": "Unload an Asterisk module.",
248                                         "nickname": "unloadModule",
249                                         "responseClass": "void",
250                                         "parameters": [
251                                                 {
252                                                         "name": "moduleName",
253                                                         "description": "Module's name",
254                                                         "paramType": "path",
255                                                         "required": true,
256                                                         "allowMultiple": false,
257                                                         "dataType": "string"
258                                                 }
259                                         ],
260                                         "errorResponses": [
261                                                 {
262                                                         "code": 404,
263                                                         "reason": "Module not found in running modules."
264                                                 },
265                                                 {
266                                                         "code": 409,
267                                                         "reason": "Module could not be unloaded."
268                                                 }
269                                         ]
270                                 },
271                                 {
272                                         "httpMethod": "PUT",
273                                         "summary": "Reload an Asterisk module.",
274                                         "nickname": "reloadModule",
275                                         "responseClass": "void",
276                                         "parameters": [
277                                                 {
278                                                         "name": "moduleName",
279                                                         "description": "Module's name",
280                                                         "paramType": "path",
281                                                         "required": true,
282                                                         "allowMultiple": false,
283                                                         "dataType": "string"
284                                                 }
285                                         ],
286                                         "errorResponses": [
287                                                 {
288                                                         "code": 404,
289                                                         "reason": "Module not found in running modules."
290                                                 },
291                                                 {
292                                                         "code": 409,
293                                                         "reason": "Module could not be reloaded."
294                                                 }
295                                         ]
296                                 }
297                         ]
298                 },
299                 {
300                         "path": "/asterisk/variable",
301                         "description": "Global variables",
302                         "operations": [
303                                 {
304                                         "httpMethod": "GET",
305                                         "summary": "Get the value of a global variable.",
306                                         "nickname": "getGlobalVar",
307                                         "responseClass": "Variable",
308                                         "parameters": [
309                                                 {
310                                                         "name": "variable",
311                                                         "description": "The variable to get",
312                                                         "paramType": "query",
313                                                         "required": true,
314                                                         "allowMultiple": false,
315                                                         "dataType": "string"
316                                                 }
317                                         ],
318                                         "errorResponses": [
319                                                 {
320                                                         "code": 400,
321                                                         "reason": "Missing variable parameter."
322                                                 }
323                                         ]
324                                 },
325                                 {
326                                         "httpMethod": "POST",
327                                         "summary": "Set the value of a global variable.",
328                                         "nickname": "setGlobalVar",
329                                         "responseClass": "void",
330                                         "parameters": [
331                                                 {
332                                                         "name": "variable",
333                                                         "description": "The variable to set",
334                                                         "paramType": "query",
335                                                         "required": true,
336                                                         "allowMultiple": false,
337                                                         "dataType": "string"
338                                                 },
339                                                 {
340                                                         "name": "value",
341                                                         "description": "The value to set the variable to",
342                                                         "paramType": "query",
343                                                         "required": false,
344                                                         "allowMultiple": false,
345                                                         "dataType": "string"
346                                                 }
347                                         ],
348                                         "errorResponses": [
349                                                 {
350                                                         "code": 400,
351                                                         "reason": "Missing variable parameter."
352                                                 }
353                                         ]
354                                 }
355                         ]
356                 }
357         ],
358         "models": {
359                 "BuildInfo": {
360                         "id": "BuildInfo",
361                         "description": "Info about how Asterisk was built",
362                         "properties": {
363                                 "os": {
364                                         "required": true,
365                                         "type": "string",
366                                         "description": "OS Asterisk was built on."
367                                 },
368                                 "kernel": {
369                                         "required": true,
370                                         "type": "string",
371                                         "description": "Kernel version Asterisk was built on."
372                                 },
373                                 "options": {
374                                         "required": true,
375                                         "type": "string",
376                                         "description": "Compile time options, or empty string if default."
377                                 },
378                                 "machine": {
379                                         "required": true,
380                                         "type": "string",
381                                         "description": "Machine architecture (x86_64, i686, ppc, etc.)"
382                                 },
383                                 "date": {
384                                         "required": true,
385                                         "type": "string",
386                                         "description": "Date and time when Asterisk was built."
387                                 },
388                                 "user": {
389                                         "required": true,
390                                         "type": "string",
391                                         "description": "Username that build Asterisk"
392                                 }
393                         }
394                 },
395                 "SystemInfo": {
396                         "id": "SystemInfo",
397                         "description": "Info about Asterisk",
398                         "properties": {
399                                 "version": {
400                                         "required": true,
401                                         "type": "string",
402                                         "description": "Asterisk version."
403                                 },
404                                 "entity_id": {
405                                         "required": true,
406                                         "type": "string",
407                                         "description": ""
408                                 }
409                         }
410                 },
411                 "SetId": {
412                         "id": "SetId",
413                         "description": "Effective user/group id",
414                         "properties": {
415                                 "user": {
416                                         "required": true,
417                                         "type": "string",
418                                         "description": "Effective user id."
419                                 },
420                                 "group": {
421                                         "required": true,
422                                         "type": "string",
423                                         "description": "Effective group id."
424                                 }
425                         }
426                 },
427                 "ConfigInfo": {
428                         "id": "ConfigInfo",
429                         "description": "Info about Asterisk configuration",
430                         "properties": {
431                                 "name": {
432                                         "required": true,
433                                         "type": "string",
434                                         "description": "Asterisk system name."
435                                 },
436                                 "default_language": {
437                                         "required": true,
438                                         "type": "string",
439                                         "description": "Default language for media playback."
440                                 },
441                                 "max_channels": {
442                                         "required": false,
443                                         "type": "int",
444                                         "description": "Maximum number of simultaneous channels."
445                                 },
446                                 "max_open_files": {
447                                         "required": false,
448                                         "type": "int",
449                                         "description": "Maximum number of open file handles (files, sockets)."
450                                 },
451                                 "max_load": {
452                                         "required": false,
453                                         "type": "double",
454                                         "description": "Maximum load avg on system."
455                                 },
456                                 "setid": {
457                                         "required": true,
458                                         "type": "SetId",
459                                         "description": "Effective user/group id for running Asterisk."
460                                 }
461                         }
462                 },
463                 "StatusInfo": {
464                         "id": "StatusInfo",
465                         "description": "Info about Asterisk status",
466                         "properties": {
467                                 "startup_time": {
468                                         "required": true,
469                                         "type": "Date",
470                                         "description": "Time when Asterisk was started."
471                                 },
472                                 "last_reload_time": {
473                                         "required": true,
474                                         "type": "Date",
475                                         "description": "Time when Asterisk was last reloaded."
476                                 }
477                         }
478                 },
479                 "AsteriskInfo": {
480                         "id": "AsteriskInfo",
481                         "description": "Asterisk system information",
482                         "properties": {
483                                 "build": {
484                                         "required": false,
485                                         "type": "BuildInfo",
486                                         "description": "Info about how Asterisk was built"
487                                 },
488                                 "system": {
489                                         "required": false,
490                                         "type": "SystemInfo",
491                                         "description": "Info about the system running Asterisk"
492                                 },
493                                 "config": {
494                                         "required": false,
495                                         "type": "ConfigInfo",
496                                         "description": "Info about Asterisk configuration"
497                                 },
498                                 "status": {
499                                         "required": false,
500                                         "type": "StatusInfo",
501                                         "description": "Info about Asterisk status"
502                                 }
503                         }
504                 },
505                 "Module": {
506                         "id": "Module",
507                         "description": "Details of an Asterisk module",
508                         "properties": {
509                                 "name": {
510                                         "type": "string",
511                                         "description": "The name of this module",
512                                         "required": true
513                                 },
514                                 "description": {
515                                         "type": "string",
516                                         "description": "The description of this module",
517                                         "required": true
518                                 },
519                                 "use_count": {
520                                         "type": "int",
521                                         "description": "The number of times this module is being used",
522                                         "required": true
523                                 },
524                                 "status": {
525                                         "type": "string",
526                                         "description": "The running status of this module",
527                                         "required": true
528                                 },
529                                 "support_level": {
530                                         "type": "string",
531                                         "description": "The support state of this module",
532                                         "required": true
533                                 }
534                         }
535                 },
536                 "Variable": {
537                         "id": "Variable",
538                         "description": "The value of a channel variable",
539                         "properties": {
540                                 "value": {
541                                         "required": true,
542                                         "type": "string",
543                                         "description": "The value of the variable requested"
544                                 }
545                         }
546                 },
547                 "ConfigTuple": {
548                         "id": "ConfigTuple",
549                         "description": "A key/value pair that makes up part of a configuration object.",
550                         "properties": {
551                                 "attribute": {
552                                         "required": true,
553                                         "type": "string",
554                                         "description": "A configuration object attribute."
555                                 },
556                                 "value": {
557                                         "required": true,
558                                         "type": "string",
559                                         "description": "The value for the attribute."
560                                 }
561                         }
562                 }
563         }
564 }