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 | |
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')
-rw-r--r-- | rest-api/README.txt | 9 | ||||
-rw-r--r-- | rest-api/api-docs/asterisk.json | 47 | ||||
-rw-r--r-- | rest-api/api-docs/bridges.json | 257 | ||||
-rw-r--r-- | rest-api/api-docs/channels.json | 645 | ||||
-rw-r--r-- | rest-api/api-docs/endpoints.json | 68 | ||||
-rw-r--r-- | rest-api/api-docs/events.json | 166 | ||||
-rw-r--r-- | rest-api/api-docs/playback.json | 102 | ||||
-rw-r--r-- | rest-api/api-docs/recordings.json | 270 | ||||
-rw-r--r-- | rest-api/api-docs/sounds.json | 85 | ||||
-rw-r--r-- | rest-api/resources.json | 42 |
10 files changed, 1691 insertions, 0 deletions
diff --git a/rest-api/README.txt b/rest-api/README.txt new file mode 100644 index 000000000..893bf87c3 --- /dev/null +++ b/rest-api/README.txt @@ -0,0 +1,9 @@ +<!-- Written in -*- Markdown -*- --> + +This directory contains the specification for the Asterisk RESTful +API. The API is documented using Swagger[1]. This is used to not only +generate executable documentation pages for the API, but also to +generate a lot of the boilerplate necessary for implementing the API +with Asterisk's HTTP server. + + [1]: http://swagger.wordnik.com/ diff --git a/rest-api/api-docs/asterisk.json b/rest-api/api-docs/asterisk.json new file mode 100644 index 000000000..ef6c7b864 --- /dev/null +++ b/rest-api/api-docs/asterisk.json @@ -0,0 +1,47 @@ +{ + "_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/asterisk.{format}", + "apis": [ + { + "path": "/asterisk/info", + "description": "Asterisk system information (similar to core show settings)", + "operations": [ + { + "httpMethod": "GET", + "summary": "Gets Asterisk system information.", + "nickname": "getAsteriskInfo", + "responseClass": "AsteriskInfo", + "parameters": [ + { + "name": "only", + "description": "Filter information returned", + "paramType": "query", + "required": false, + "allowMultiple": true, + "dataType": "string", + "allowableValues": { + "valueType": "LIST", + "values": [ + "version", + "modules", + "uptime" + ] + } + } + ] + } + ] + } + ], + "models": { + "AsteriskInfo": { + "id": "AsteriskInfo", + "properties": {} + } + } +} 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 + } + } + } + } +} diff --git a/rest-api/api-docs/channels.json b/rest-api/api-docs/channels.json new file mode 100644 index 000000000..c2d77b22c --- /dev/null +++ b/rest-api/api-docs/channels.json @@ -0,0 +1,645 @@ +{ + "_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/channels.{format}", + "apis": [ + { + "path": "/channels", + "description": "Active channels", + "operations": [ + { + "httpMethod": "GET", + "summary": "List active channels.", + "nickname": "getChannels", + "responseClass": "List[Channel]" + }, + { + "httpMethod": "POST", + "summary": "Create a new channel (originate).", + "nickname": "originate", + "responseClass": "Originated", + "parameters": [ + { + "name": "endpoint", + "description": "Endpoint to call. If not specified, originate is routed via dialplan", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "extension", + "description": "Extension to dial", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "context", + "description": "When routing via dialplan, the context use. If omitted, uses 'default'", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}", + "description": "Active channel", + "operations": [ + { + "httpMethod": "GET", + "summary": "Channel details.", + "nickname": "getChannel", + "responseClass": "Channel", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + } + ] + }, + { + "httpMethod": "DELETE", + "summary": "Delete (i.e. hangup) a channel.", + "nickname": "deleteChannel", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/dial", + "description": "Create a new channel (originate) and bridge to this channel", + "operations": [ + { + "httpMethod": "POST", + "summary": "Create a new channel (originate) and bridge to this channel.", + "nickname": "dial", + "responseClass": "Dialed", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "endpoint", + "description": "Endpoint to call. If not specified, dial is routed via dialplan", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "extension", + "description": "Extension to dial", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "context", + "description": "When routing via dialplan, the context use. If omitted, uses 'default'", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel not in a Stasis application" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/continue", + "description": "Exit application; continue execution in the dialplan", + "operations": [ + { + "httpMethod": "POST", + "summary": "Exit application; continue execution in the dialplan.", + "nickname": "continueInDialplan", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel not in a Stasis application" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/answer", + "description": "Answer a channel", + "operations": [ + { + "httpMethod": "POST", + "summary": "Answer a channel.", + "nickname": "answerChannel", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/mute", + "description": "Mute a channel", + "operations": [ + { + "httpMethod": "POST", + "summary": "Mute a channel.", + "nickname": "muteChannel", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "direction", + "description": "Direction in which to mute audio", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string", + "defaultValue": "both", + "allowableValues": { + "valueType": "LIST", + "values": [ + "both", + "in", + "out" + ] + } + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel not in a Stasis application" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/unmute", + "description": "Unmute a channel", + "operations": [ + { + "httpMethod": "POST", + "summary": "Unmute a channel.", + "nickname": "unmuteChannel", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "direction", + "description": "Direction in which to unmute audio", + "paramType": "query", + "required": false, + "allowMultiple": false, + "dataType": "string", + "defaultValue": "both", + "allowableValues": { + "valueType": "LIST", + "values": [ + "both", + "in", + "out" + ] + } + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel not in a Stasis application" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/hold", + "description": "Put a channel on hold", + "operations": [ + { + "httpMethod": "POST", + "summary": "Hold a channel.", + "nickname": "holdChannel", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel not in a Stasis application" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/unhold", + "description": "Remove a channel from hold", + "operations": [ + { + "httpMethod": "POST", + "summary": "Remove a channel from hold.", + "nickname": "unholdChannel", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel not in a Stasis application" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/play", + "description": "Play media to a channel", + "operations": [ + { + "httpMethod": "POST", + "summary": "Start playback of media.", + "notes": "The media URI may be any of a number of URI's. You may use http: and https: URI's, as well as sound: and recording: URI's. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)", + "nickname": "playOnChannel", + "responseClass": "Playback", + "parameters": [ + { + "name": "channelId", + "description": "Channel's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "media", + "description": "Media's URI to play.", + "paramType": "query", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel not in a Stasis application" + } + ] + } + ] + }, + { + "path": "/channels/{channelId}/record", + "description": "Record audio from a channel", + "operations": [ + { + "httpMethod": "POST", + "summary": "Start a recording.", + "notes": "Record audio from a channel. Note that this will not capture audio sent to the channel. The bridge itself has a record feature if that's what you want.", + "nickname": "recordChannel", + "responseClass": "void", + "parameters": [ + { + "name": "channelId", + "description": "Channel'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": "format", + "description": "Format to encode audio in", + "paramType": "query", + "required": true, + "allowMultiple": true, + "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", + "*", + "#" + ] + } + } + ], + "errorResponses": [ + { + "code": 404, + "reason": "Channel not found" + }, + { + "code": 409, + "reason": "Channel is not in a Stasis application." + }, + { + "code": 409, + "reason": "The channel is currently bridges with other channels." + } + ] + } + ] + } + ], + "models": { + "Originated": { + "id": "Originated", + "properties": {} + }, + "Dialed": { + "id": "Dialed", + "properties": {} + }, + "DialplanCEP": { + "id": "DialplanCEP", + "properties": { + "context": { + "required": true, + "type": "string", + "description": "Context in the dialplan" + }, + "exten": { + "required": true, + "type": "string", + "description": "Extension in the dialplan" + }, + "priority": { + "required": true, + "type": "long", + "description": "Priority in the dialplan" + } + } + }, + "CallerID": { + "id": "CallerID", + "properties": { + "name": { + "required": true, + "type": "string" + }, + "number": { + "required": true, + "type": "string" + } + } + }, + "Channel": { + "id": "Channel", + "properties": { + "uniqueid": { + "required": true, + "type": "string", + "description": "Unique identifier of the channel" + }, + "name": { + "required": true, + "type": "string", + "description": "Name of the channel (i.e. SIP/foo-0000a7e3)" + }, + "state": { + "required": true, + "type": "string" + }, + "accountcode": { + "required": true, + "type": "string" + }, + "peeraccount": { + "required": true, + "type": "string" + }, + "userfield": { + "required": true, + "type": "string" + }, + "linkedid": { + "required": true, + "type": "string" + }, + "parkinglot": { + "required": true, + "type": "string" + }, + "hangupsource": { + "required": true, + "type": "string" + }, + "appl": { + "required": true, + "type": "string", + "description": "Currently executing dialplan application" + }, + "data": { + "required": true, + "type": "string", + "description": "Arguments passed to appl" + }, + "dialplan": { + "required": true, + "type": "DialplanCEP", + "description": "Current location in the dialplan" + }, + "caller": { + "required": true, + "type": "CallerID" + }, + "connected": { + "required": true, + "type": "CallerID" + }, + "creationtime": { + "required": true, + "type": "Date", + "description": "Timestamp when channel was created" + } + } + } + } +} diff --git a/rest-api/api-docs/endpoints.json b/rest-api/api-docs/endpoints.json new file mode 100644 index 000000000..43b8453d7 --- /dev/null +++ b/rest-api/api-docs/endpoints.json @@ -0,0 +1,68 @@ +{ + "_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/endpoints.{format}", + "apis": [ + { + "path": "/endpoints", + "description": "Asterisk endpoints", + "operations": [ + { + "httpMethod": "GET", + "summary": "List available endoints.", + "nickname": "getEndpoints", + "responseClass": "List[Endpoint]", + "parameters": [ + { + "name": "withType", + "description": "Filter endpoints by type (sip,iax2,dhadi,...)", + "paramType": "query", + "required": false, + "allowMultiple": true, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/endpoints/{endpointId}", + "description": "Single endpoint", + "operations": [ + { + "httpMethod": "GET", + "summary": "Details for an endpoint.", + "nickname": "getEndpoint", + "responseClass": "Endpoint", + "parameters": [ + { + "name": "endpointId", + "description": "ID of the endpoint", + "paramType": "path", + "dataType": "string" + } + ] + } + ] + } + ], + "models": { + "Endpoint": { + "id": "Endpoint", + "properties": { + "technology": { + "type": "string", + "required": true + }, + "name": { + "type": "string", + "required": true + } + } + } + } +} diff --git a/rest-api/api-docs/events.json b/rest-api/api-docs/events.json new file mode 100644 index 000000000..b1389017f --- /dev/null +++ b/rest-api/api-docs/events.json @@ -0,0 +1,166 @@ +{ + "_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/events.{format}", + "apis": [ + { + "path": "/events", + "description": "Events from Asterisk to applications", + "operations": [ + { + "httpMethod": "GET", + "summary": "WebSocket connection for events.", + "nickname": "eventWebsocket", + "responseClass": "Event", + "parameters": [ + { + "name": "app", + "description": "Comma seperated list of applications to subscribe to.", + "paramType": "query", + "required": true, + "allowMultiple": true, + "dataType": "string" + }, + { + "name": "Upgrade", + "description": "RFC6455 header for upgrading a connection to a websocket.", + "paramType": "header", + "required": true, + "dataType": "string", + "allowableValues": { + "valueType": "LIST", + "values": [ + "websocket" + ] + } + } + ] + } + ] + } + ], + "models": { + "Event": { + "id": "Event", + "description": "Asynchronous events from Asterisk. The non-required fields of this object are mutually exclusive.", + "properties": { + "application": { + "type": "string", + "description": "Name of the application receiving the event.", + "required": true + }, + "application_replaced": { "type": "ApplicationReplaced" }, + "bridge_created": { "type": "BridgeCreated" }, + "bridge_destroyed": { "type": "BridgeDestroyed" }, + "channel_entered_bridge": { "type": "ChannelEnteredBridge" }, + "channel_left_bridge": { "type": "ChannelLeftBridge" }, + "channel_state_change": { "type": "ChannelStateChange" }, + "dtmf_received": { "type": "DtmfReceived" }, + "stasis_end": { "type": "StasisEnd" }, + "stasis_start": { "type": "StasisStart" } + } + }, + "ApplicationReplaced": { + "id": "ApplicationReplaced", + "description": "Notification that another WebSocket has taken over for an application.", + "notes": "An application may only be subscribed to by a single WebSocket at a time. If multiple WebSockets attempt to subscribe to the same application, the newer WebSocket wins, and the older one receives this event.", + "properties": { + "application": { + "type": "string" + } + } + }, + "BridgeCreated": { + "id": "BridgeCreated", + "description": "Notification that a bridge has been created.", + "properties": { + "bridge": { + "type": "Bridge" + } + } + }, + "BridgeDestroyed": { + "id": "BridgeDestroyed", + "description": "Notification that a bridge has been destroyed.", + "properties": { + "bridge": { + "type": "Bridge" + } + } + }, + "ChannelEnteredBridge": { + "id": "ChannelEnteredBridge", + "description": "Notification that a channel has entered a bridge.", + "properties": { + "bridge": { + "type": "Bridge" + }, + "channel": { + "type": "Channel" + } + } + }, + "ChannelLeftBridge": { + "id": "ChannelLeftBridge", + "description": "Notification that a channel has left a bridge.", + "properties": { + "bridge": { + "type": "Bridge" + }, + "channel": { + "type": "Channel" + } + } + }, + "ChannelStateChange": { + "id": "ChannelStateChange", + "description": "Notification of a channel's state change.", + "properties": { + "channel_info": { + "type": "Channel" + } + } + }, + "DtmfReceived": { + "id": "DtmfReceived", + "description": "DTMF received on a channel.", + "notes": "This event is sent when the DTMF ends. There is no notification about the start of DTMF", + "properties": { + "digit": { + "type": "string", + "description": "DTMF digit received (0-9, A-E, # or *)" + }, + "channel": { + "type": "Channel", + "description": "The channel on which DTMF was received" + } + } + }, + "StasisEnd": { + "id": "StasisEnd", + "description": "Notification that a channel has left a Stasis appliction.", + "properties": { + "channel_info": { + "type": "Channel" + } + } + }, + "StasisStart": { + "id": "StasisStart", + "description": "Notification that a channel has entered a Stasis appliction.", + "properties": { + "args": { + "type": "List[string]", + "description": "Arguments to the application" + }, + "channel_info": { + "type": "Channel" + } + } + } + } +} diff --git a/rest-api/api-docs/playback.json b/rest-api/api-docs/playback.json new file mode 100644 index 000000000..aa758781c --- /dev/null +++ b/rest-api/api-docs/playback.json @@ -0,0 +1,102 @@ +{ + "_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/playback.{format}", + "apis": [ + { + "path": "/playback/{playbackId}", + "description": "Control object for a playback operation.", + "operations": [ + { + "httpMethod": "GET", + "summary": "Get a playback's details.", + "nickname": "getPlayback", + "responseClass": "Playback", + "parameters": [ + { + "name": "playbackId", + "description": "Playback's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + }, + { + "httpMethod": "DELETE", + "summary": "Stop a playback.", + "nickname": "stopPlayback", + "responseClass": "Playback", + "parameters": [ + { + "name": "playbackId", + "description": "Playback's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/playback/{playbackId}/control", + "description": "Control object for a playback operation.", + "operations": [ + { + "httpMethod": "POST", + "summary": "Get a playback's details.", + "nickname": "controlPlayback", + "responseClass": "Playback", + "parameters": [ + { + "name": "playbackId", + "description": "Playback's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + }, + { + "name": "operation", + "description": "Operation to perform on the playback.", + "paramType": "query", + "required": true, + "allowMultiple": false, + "dataType": "string", + "allowableValues": { + "valueType": "LIST", + "values": [ + "play", + "pause", + "rewind", + "fast-forward", + "speed-up", + "slow-down" + ] + } + } + ] + } + ] + } + ], + "models": { + "Playback": { + "id": "Playback", + "properties": { + "id": { + "required": true, + "description": "Playback's identifier.", + "type": "string" + } + } + } + } +} diff --git a/rest-api/api-docs/recordings.json b/rest-api/api-docs/recordings.json new file mode 100644 index 000000000..2f5f92a08 --- /dev/null +++ b/rest-api/api-docs/recordings.json @@ -0,0 +1,270 @@ +{ + "_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/recordings.{format}", + "apis": [ + { + "path": "/recordings", + "description": "Recordings", + "operations": [ + { + "httpMethod": "GET", + "summary": "List all recordings.", + "nickname": "getRecordings", + "responseClass": "List[Recording]" + } + ] + }, + { + "path": "/recordings/stored", + "description": "Recordings", + "operations": [ + { + "httpMethod": "GET", + "summary": "List recordings that are complete.", + "nickname": "getStoredRecordings", + "responseClass": "List[StoredRecording]" + } + ] + }, + { + "path": "/recordings/stored/{recordingId}", + "description": "Individual recording", + "operations": [ + { + "httpMethod": "GET", + "summary": "Get a stored recording's details.", + "nickname": "getStoredRecording", + "responseClass": "StoredRecording", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + }, + { + "httpMethod": "DELETE", + "summary": "Delete a stored recording.", + "nickname": "deleteStoredRecording", + "responseClass": "void", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/recordings/live", + "description": "Recordings that are in progress", + "operations": [ + { + "httpMethod": "GET", + "summary": "List libe recordings.", + "nickname": "getLiveRecordings", + "responseClass": "List[LiveRecording]" + } + ] + }, + { + "path": "/recordings/live/{recordingId}", + "description": "A recording that is in progress", + "operations": [ + { + "httpMethod": "GET", + "summary": "List live recordings.", + "nickname": "getLiveRecording", + "responseClass": "LiveRecording", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + }, + { + "httpMethod": "DELETE", + "summary": "Stop a live recording and discard it.", + "nickname": "cancelRecording", + "responseClass": "void", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/recordings/live/{recordingId}/stop", + "operations": [ + { + "httpMethod": "POST", + "summary": "Stop a live recording and store it.", + "nickname": "stopRecording", + "responseClass": "void", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/recordings/live/{recordingId}/pause", + "operations": [ + { + "httpMethod": "POST", + "summary": "Pause a live recording.", + "nickname": "pauseRecording", + "responseClass": "void", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/recordings/live/{recordingId}/unpause", + "operations": [ + { + "httpMethod": "POST", + "summary": "Unpause a live recording.", + "nickname": "unpauseRecording", + "responseClass": "void", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/recordings/live/{recordingId}/mute", + "operations": [ + { + "httpMethod": "POST", + "summary": "Mute a live recording.", + "nickname": "muteRecording", + "responseClass": "void", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + }, + { + "path": "/recordings/live/{recordingId}/unmute", + "operations": [ + { + "httpMethod": "POST", + "summary": "Unmute a live recording.", + "nickname": "unmuteRecording", + "responseClass": "void", + "parameters": [ + { + "name": "recordingId", + "description": "Recording's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + } + ], + "models": { + "Recording": { + "id": "Recording", + "properties": { + "id": { + "required": true, + "type": "string" + } + } + }, + "StoredRecording": { + "id": "StoredRecording", + "properties": { + "id": { + "required": true, + "type": "string" + }, + "formats": { + "required": true, + "type": "List[string]" + }, + "durationSeconds": { + "required": false, + "type": "int" + }, + "time": { + "description": "Time recording was started", + "required": false, + "type": "Date" + } + } + }, + "LiveRecording": { + "id": "LiveRecording", + "properties": { + "id": { + "required": true, + "type": "string" + } + } + } + } +} diff --git a/rest-api/api-docs/sounds.json b/rest-api/api-docs/sounds.json new file mode 100644 index 000000000..23d02257d --- /dev/null +++ b/rest-api/api-docs/sounds.json @@ -0,0 +1,85 @@ +{ + "_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/sounds.{format}", + "apis": [ + { + "path": "/sounds", + "description": "Sounds", + "operations": [ + { + "httpMethod": "GET", + "summary": "List all sounds.", + "nickname": "getSounds", + "responseClass": "List[Sound]", + "parameters": [ + { + "name": "lang", + "paramType": "query", + "dataType": "string", + "required": false + }, + { + "name": "format", + "paramType": "query", + "dataType": "string", + "required": false, + "__note": "core show translation can show translation paths between formats, along with relative costs. so this could be just installed format, or we could follow that for transcoded formats." + } + ] + } + ] + }, + { + "path": "/sounds/{soundId}", + "description": "Individual sound", + "operations": [ + { + "httpMethod": "GET", + "summary": "Get a sound's details.", + "nickname": "getStoredSound", + "responseClass": "Sound", + "parameters": [ + { + "name": "soundId", + "description": "Sound's id", + "paramType": "path", + "required": true, + "allowMultiple": false, + "dataType": "string" + } + ] + } + ] + } + ], + "models": { + "Sound": { + "id": "Sound", + "properties": { + "id": { + "required": true, + "description": "Sound's identifier.", + "type": "string" + }, + "text": { + "required": false, + "description": "Text description of the sound, usually the words spoken.", + "type": "string" + }, + "lang": { + "required": true, + "type": "string" + }, + "formats": { + "required": true, + "type": "List[string]" + } + } + } + } +} diff --git a/rest-api/resources.json b/rest-api/resources.json new file mode 100644 index 000000000..d9a0c5b35 --- /dev/null +++ b/rest-api/resources.json @@ -0,0 +1,42 @@ +{ + "_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", + "apis": [ + { + "path": "/api-docs/asterisk.{format}", + "description": "Asterisk resources" + }, + { + "path": "/api-docs/endpoints.{format}", + "description": "Endpoint resources" + }, + { + "path": "/api-docs/channels.{format}", + "description": "Channel resources" + }, + { + "path": "/api-docs/bridges.{format}", + "description": "Bridge resources" + }, + { + "path": "/api-docs/recordings.{format}", + "description": "Recording resources" + }, + { + "path": "/api-docs/sounds.{format}", + "description": "Sound resources" + }, + { + "path": "/api-docs/playback.{format}", + "description": "Playback control resources" + }, + { + "path": "/api-docs/events.{format}", + "description": "WebSocket resource" + } + ] +} |