Update API versions and UPGRADE/CHANGES for 12.2.0
[asterisk/asterisk.git] / rest-api / api-docs / channels.json
index dd611cc..d940f43 100644 (file)
@@ -2,7 +2,7 @@
        "_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.",
        "_author": "David M. Lee, II <dlee@digium.com>",
        "_svn_revision": "$Revision$",
-       "apiVersion": "0.0.1",
+       "apiVersion": "1.2.0",
        "swaggerVersion": "1.1",
        "basePath": "http://localhost:8088/stasis",
        "resourcePath": "/api-docs/channels.{format}",
                                                        "allowMultiple": false,
                                                        "dataType": "int",
                                                        "defaultValue": 30
+                                               },
+                                               {
+                                                       "name": "variables",
+                                                       "description": "The 'variables' key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { 'endpoint': 'SIP/Alice', 'variables': { 'CALLERID(name)': 'Alice' } }",
+                                                       "paramType": "body",
+                                                       "required": false,
+                                                       "dataType": "containers",
+                                                       "allowMultiple": false
+                                               },
+                                               {
+                                                       "name": "channelId",
+                                                       "description": "The unique id to assign the channel on creation.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "otherChannelId",
+                                                       "description": "The unique id to assign the second channel when using local channels.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
                                                }
                                        ],
                                        "errorResponses": [
                                        ]
                                },
                                {
+                                       "httpMethod": "POST",
+                                       "summary": "Create a new channel (originate with id).",
+                                       "notes": "The new channel is created immediately and a snapshot of it returned. If a Stasis application is provided it will be automatically subscribed to the originated channel for further events and updates.",
+                                       "nickname": "originateWithId",
+                                       "responseClass": "Channel",
+                                       "parameters": [
+                                               {
+                                                       "name": "channelId",
+                                                       "description": "The unique id to assign the channel on creation.",
+                                                       "paramType": "path",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "endpoint",
+                                                       "description": "Endpoint to call.",
+                                                       "paramType": "query",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "extension",
+                                                       "description": "The extension to dial after the endpoint answers",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "context",
+                                                       "description": "The context to dial after the endpoint answers. If omitted, uses 'default'",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "priority",
+                                                       "description": "The priority to dial after the endpoint answers. If omitted, uses 1",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "long"
+                                               },
+                                               {
+                                                       "name": "app",
+                                                       "description": "The application that is subscribed to the originated channel, and passed to the Stasis application.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "appArgs",
+                                                       "description": "The application arguments to pass to the Stasis application.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "callerId",
+                                                       "description": "CallerID to use when dialing the endpoint or extension.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "timeout",
+                                                       "description": "Timeout (in seconds) before giving up dialing, or -1 for no timeout.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "int",
+                                                       "defaultValue": 30
+                                               },
+                                               {
+                                                       "name": "variables",
+                                                       "description": "The 'variables' key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { 'endpoint': 'SIP/Alice', 'variables': { 'CALLERID(name)': 'Alice' } }",
+                                                       "paramType": "body",
+                                                       "required": false,
+                                                       "dataType": "containers",
+                                                       "allowMultiple": false
+                                               },
+                                               {
+                                                       "name": "otherChannelId",
+                                                       "description": "The unique id to assign the second channel when using local channels.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 400,
+                                                       "reason": "Invalid parameters for originating a channel."
+                                               }
+                                       ]
+
+                               },
+                               {
                                        "httpMethod": "DELETE",
                                        "summary": "Delete (i.e. hangup) a channel.",
                                        "nickname": "hangup",
                                {
                                        "httpMethod": "POST",
                                        "summary": "Play music on hold to a channel.",
-                                       "notes": "Using media operations such as playOnChannel on a channel playing MOH in this manner will suspend MOH without resuming automatically. If continuing music on hold is desired, the stasis application must reinitiate music on hold.",
+                                       "notes": "Using media operations such as /play on a channel playing MOH in this manner will suspend MOH without resuming automatically. If continuing music on hold is desired, the stasis application must reinitiate music on hold.",
                                        "nickname": "startMoh",
                                        "responseClass": "void",
                                        "parameters": [
                        ]
                },
                {
+                       "path": "/channels/{channelId}/silence",
+                       "description": "Play silence to a channel",
+                       "operations": [
+                               {
+                                       "httpMethod": "POST",
+                                       "summary": "Play silence to a channel.",
+                                       "notes": "Using media operations such as /play on a channel playing silence in this manner will suspend silence without resuming automatically.",
+                                       "nickname": "startSilence",
+                                       "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"
+                                               }
+                                       ]
+                               },
+                               {
+                                       "httpMethod": "DELETE",
+                                       "summary": "Stop playing silence to a channel.",
+                                       "nickname": "stopSilence",
+                                       "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": [
                                                        "allowMultiple": false,
                                                        "dataType": "int",
                                                        "defaultValue": 3000
+                                               },
+                                               {
+                                                       "name": "playbackId",
+                                                       "description": "Playback ID.",
+                                                       "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}/play/{playbackId}",
+                       "description": "Play media to a channel",
+                       "operations": [
+                               {
+                                       "httpMethod": "POST",
+                                       "summary": "Start playback of media and specify the playbackId.",
+                                       "notes": "The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
+                                       "nickname": "playWithId",
+                                       "responseClass": "Playback",
+                                       "parameters": [
+                                               {
+                                                       "name": "channelId",
+                                                       "description": "Channel's id",
+                                                       "paramType": "path",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "playbackId",
+                                                       "description": "Playback 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"
+                                               },
+                                               {
+                                                       "name": "lang",
+                                                       "description": "For sounds, selects language for sound.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "offsetms",
+                                                       "description": "Number of media to skip before playing.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "int"
+                                               },
+                                               {
+                                                       "name": "skipms",
+                                                       "description": "Number of milliseconds to skip for forward/reverse operations.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "int",
+                                                       "defaultValue": 3000
                                                }
                                        ],
                                        "errorResponses": [
                                        ]
                                }
                        ]
+               },
+               {
+                       "path": "/channels/{channelId}/snoop",
+                       "description": "Snoop (spy/whisper) on a channel",
+                       "operations": [
+                               {
+                                       "httpMethod": "POST",
+                                       "summary": "Start snooping.",
+                                       "notes": "Snoop (spy/whisper) on a specific channel.",
+                                       "nickname": "snoopChannel",
+                                       "responseClass": "Channel",
+                                       "parameters": [
+                                               {
+                                                       "name": "channelId",
+                                                       "description": "Channel's id",
+                                                       "paramType": "path",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "spy",
+                                                       "description": "Direction of audio to spy on",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string",
+                                                       "defaultValue": "none",
+                                                       "allowableValues": {
+                                                               "valueType": "LIST",
+                                                               "values": [
+                                                                       "none",
+                                                                       "both",
+                                                                       "out",
+                                                                       "in"
+                                                               ]
+                                                       }
+                                               },
+                                               {
+                                                       "name": "whisper",
+                                                       "description": "Direction of audio to whisper into",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string",
+                                                       "defaultValue": "none",
+                                                       "allowableValues": {
+                                                               "valueType": "LIST",
+                                                               "values": [
+                                                                       "none",
+                                                                       "both",
+                                                                       "out",
+                                                                       "in"
+                                                               ]
+                                                       }
+                                               },
+                                               {
+                                                       "name": "app",
+                                                       "description": "Application the snooping channel is placed into",
+                                                       "paramType": "query",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "appArgs",
+                                                       "description": "The application arguments to pass to the Stasis application",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "snoopId",
+                                                       "description": "Unique ID to assign to snooping channel",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 400,
+                                                       "reason": "Invalid parameters"
+                                               },
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Channel not found"
+                                               }
+                                       ]
+                               }
+                       ]
+               },
+               {
+                       "path": "/channels/{channelId}/snoop/{snoopId}",
+                       "description": "Snoop (spy/whisper) on a channel",
+                       "operations": [
+                               {
+                                       "httpMethod": "POST",
+                                       "summary": "Start snooping.",
+                                       "notes": "Snoop (spy/whisper) on a specific channel.",
+                                       "nickname": "snoopChannelWithId",
+                                       "responseClass": "Channel",
+                                       "parameters": [
+                                               {
+                                                       "name": "channelId",
+                                                       "description": "Channel's id",
+                                                       "paramType": "path",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "snoopId",
+                                                       "description": "Unique ID to assign to snooping channel",
+                                                       "paramType": "path",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "spy",
+                                                       "description": "Direction of audio to spy on",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string",
+                                                       "defaultValue": "none",
+                                                       "allowableValues": {
+                                                               "valueType": "LIST",
+                                                               "values": [
+                                                                       "none",
+                                                                       "both",
+                                                                       "out",
+                                                                       "in"
+                                                               ]
+                                                       }
+                                               },
+                                               {
+                                                       "name": "whisper",
+                                                       "description": "Direction of audio to whisper into",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string",
+                                                       "defaultValue": "none",
+                                                       "allowableValues": {
+                                                               "valueType": "LIST",
+                                                               "values": [
+                                                                       "none",
+                                                                       "both",
+                                                                       "out",
+                                                                       "in"
+                                                               ]
+                                                       }
+                                               },
+                                               {
+                                                       "name": "app",
+                                                       "description": "Application the snooping channel is placed into",
+                                                       "paramType": "query",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "appArgs",
+                                                       "description": "The application arguments to pass to the Stasis application",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 400,
+                                                       "reason": "Invalid parameters"
+                                               },
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Channel not found"
+                                               }
+                                       ]
+                               }
+                       ]
                }
        ],
        "models": {