ARI: External Media

The Channel resource has a new sub-resource "externalMedia".
This allows an application to create a channel for the sole purpose
of exchanging media with an external server.  Once created, this
channel could be placed into a bridge with existing channels to
allow the external server to inject audio into the bridge or
receive audio from the bridge.
See https://wiki.asterisk.org/wiki/display/AST/External+Media+and+ARI
for more information.

Change-Id: I9618899198880b4c650354581b50c0401b58bc46

rest-api/api-docs/channels.json

@@ -1748,6 +1748,131 @@
 					]
 				}
 			]
+		},
+		{
+			"path": "/channels/externalMedia",
+			"description": "Create a channel to an External Media source/sink.",
+			"operations": [
+				{
+					"httpMethod": "POST",
+					"summary": "Start an External Media session.",
+					"notes": "Create a channel to an External Media source/sink.",
+					"nickname": "externalMedia",
+					"responseClass": "ExternalMedia",
+					"parameters": [
+						{
+							"name": "channelId",
+							"description": "The unique id to assign the channel on creation.",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "app",
+							"description": "Stasis Application to place channel into",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"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": "external_host",
+							"description": "Hostname/ip:port of external host",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "encapsulation",
+							"description": "Payload encapsulation protocol",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string",
+							"defaultValue": "rtp",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"rtp"
+								]
+							}
+						},
+						{
+							"name": "transport",
+							"description": "Transport protocol",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string",
+							"defaultValue": "udp",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"udp"
+								]
+							}
+						},
+						{
+							"name": "connection_type",
+							"description": "Connection type (client/server)",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string",
+							"defaultValue": "client",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"client"
+								]
+							}
+						},
+						{
+							"name": "format",
+							"description": "Format to encode audio in",
+							"paramType": "query",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "direction",
+							"description": "External media direction",
+							"paramType": "query",
+							"required": false,
+							"allowMultiple": false,
+							"dataType": "string",
+							"defaultValue": "both",
+							"allowableValues": {
+								"valueType": "LIST",
+								"values": [
+									"both"
+								]
+							}
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 400,
+							"reason": "Invalid parameters"
+						},
+						{
+							"code": 409,
+							"reason": "Channel is not in a Stasis application; Channel is already bridged"
+						}
+					]
+				}
+			]
 		}
 	],
 	"models": {
@@ -2034,6 +2159,27 @@
 					"description": "Channel variables"
 				}
 			}
+		},
+		"ExternalMedia": {
+			"id": "ExternalMedia",
+			"description": "ExternalMedia session.",
+			"properties": {
+				"channel": {
+					"required": true,
+					"type": "Channel",
+					"description": "The Asterisk channel representing the external media"
+				},
+				"local_address": {
+					"required": false,
+					"type": "string",
+					"description": "The local ip address used" 
+				},
+				"local_port": {
+					"required": false,
+					"type": "int",
+					"description": "The local ip port used" 
+				}
+			}
 		}
 	}
 }