diff options
author | David M. Lee <dlee@digium.com> | 2013-04-22 14:58:53 +0000 |
---|---|---|
committer | David M. Lee <dlee@digium.com> | 2013-04-22 14:58:53 +0000 |
commit | 1c21b8575bfd70b98b1102fd3dd09fc0bc335e14 (patch) | |
tree | 9a6ef6074e545ad2768bc1994e1a233fc1443729 /rest-api/api-docs/bridges.json | |
parent | 1871017cc6bd2e2ce7c638eeb6813e982377a521 (diff) |
This patch adds a RESTful HTTP interface to Asterisk.
The API itself is documented using Swagger, a lightweight mechanism for
documenting RESTful API's using JSON. This allows us to use swagger-ui
to provide executable documentation for the API, generate client
bindings in different languages, and generate a lot of the boilerplate
code for implementing the RESTful bindings. The API docs live in the
rest-api/ directory.
The RESTful bindings are generated from the Swagger API docs using a set
of Mustache templates. The code generator is written in Python, and
uses Pystache. Pystache has no dependencies, and be installed easily
using pip. Code generation code lives in rest-api-templates/.
The generated code reduces a lot of boilerplate when it comes to
handling HTTP requests. It also helps us have greater consistency in the
REST API.
(closes issue ASTERISK-20891)
Review: https://reviewboard.asterisk.org/r/2376/
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386232 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'rest-api/api-docs/bridges.json')
-rw-r--r-- | rest-api/api-docs/bridges.json | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/rest-api/api-docs/bridges.json b/rest-api/api-docs/bridges.json new file mode 100644 index 000000000..fd0971a4d --- /dev/null +++ b/rest-api/api-docs/bridges.json @@ -0,0 +1,257 @@ +{ + "_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.", + "_author": "David M. Lee, II <dlee@digium.com>", + "_svn_revision": "$Revision$", + "apiVersion": "0.0.1", + "swaggerVersion": "1.1", + "basePath": "http://localhost:8088/stasis", + "resourcePath": "/api-docs/bridges.{format}", + "apis": [ + { + "path": "/bridges", + "description": "Active bridges", + "operations": [ + { + "httpMethod": "GET", + "summary": "List active bridges.", + "nickname": "getBridges", + "responseClass": "List[Bridge]" + }, + { + "httpMethod": "POST", + "summary": "Create a new bridge.", + "notes": "This bridge persists until it has been shut down, or Asterisk has been shut down.", + "nickname": "newBridge", + "responseClass": "Bridge", + "parameters": [ + { + "name": "type", + "description": "Type of bridge to create.", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string", + "allowedValues": { + "type": "LIST", + "values": [ + "two-party", + "multi-party", + "holding" + ] + } + } + ] + } + ] + }, + { + "path": "/bridges/{bridgeId}", + "description": "Individual bridge", + "operations": [ + { + "httpMethod": "GET", + "summary": "Get bridge details.", + "nickname": "getBridge", + "responseClass": "Bridge", + "parameters": [ + { + "name": "bridgeId", + "description": "Bridge's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + }, + { + "httpMethod": "DELETE", + "summary": "Shut down a bridge bridge.", + "notes": "If any channels are in this bridge, they will be removed and resume whatever they were doing beforehand.", + "nickname": "deleteBridge", + "responseClass": "void", + "parameters": [ + { + "name": "bridgeId", + "description": "Bridge's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/bridges/{bridgeId}/addChannel", + "description": "Add a channel to a bridge", + "operations": [ + { + "httpMethod": "POST", + "summary": "Add a channel to a bridge.", + "nickname": "addChannelToBridge", + "responseClass": "void", + "parameters": [ + { + "name": "bridgeId", + "description": "Bridge's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "channel", + "description": "Channel's id", + "paramType": "query", + "required": true, + "allowMultiple": true, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/bridges/{bridgeId}/removeChannel", + "description": "Remove a channel from a bridge", + "operations": [ + { + "httpMethod": "POST", + "summary": "Remove a channel from a bridge.", + "nickname": "removeChannelFromBridge", + "responseClass": "void", + "parameters": [ + { + "name": "bridgeId", + "description": "Bridge's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "channel", + "description": "Channel's id", + "paramType": "query", + "required": true, + "allowMultiple": true, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/bridges/{bridgeId}/record", + "description": "Record audio on a bridge", + "operations": [ + { + "httpMethod": "POST", + "summary": "Start a recording.", + "notes": "This records the mixed audio from all channels participating in this bridge.", + "nickname": "recordBridge", + "responseClass": "LiveRecording", + "parameters": [ + { + "name": "bridgeId", + "description": "Bridge's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "name", + "description": "Recording's filename", + "paramType": "query", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "maxDurationSeconds", + "description": "Maximum duration of the recording, in seconds. 0 for no limit.", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "int", + "defaultValue": 0 + }, + { + "name": "maxSilenceSeconds", + "description": "Maximum duration of silence, in seconds. 0 for no limit.", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "int", + "defaultValue": 0 + }, + { + "name": "append", + "description": "If true, and recording already exists, append to recording.", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "boolean", + "defaultValue": false + }, + { + "name": "beep", + "description": "Play beep when recording begins", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "boolean", + "defaultValue": false + }, + { + "name": "terminateOn", + "description": "DTMF input to terminate recording.", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string", + "defaultValue": "none", + "allowableValues": { + "valueType": "LIST", + "values": [ + "none", + "any", + "*", + "#" + ] + } + } + ] + } + ] + } + ], + "models": { + "Bridge": { + "id": "Bridge", + "properties": { + "bridgeType": { + "type": "string", + "description": "Type of bridge technology", + "required": true, + "allowedValues": { + "type": "LIST", + "values": [ + "two-party", + "multi-party", + "holding" + ] + } + }, + "channels": { + "type": "List[string]", + "description": "Id's of channels participating in this bridge", + "required": true + } + } + } + } +} |