res_stasis_recording: Add a "target_uri" field to recording events.
[asterisk/asterisk.git] / rest-api / api-docs / bridges.json
index fd0971a..b259ca8 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.1.0",
        "swaggerVersion": "1.1",
        "basePath": "http://localhost:8088/stasis",
        "resourcePath": "/api-docs/bridges.{format}",
                        "operations": [
                                {
                                        "httpMethod": "GET",
-                                       "summary": "List active bridges.",
-                                       "nickname": "getBridges",
+                                       "summary": "List all active bridges in Asterisk.",
+                                       "nickname": "list",
                                        "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",
+                                       "nickname": "create",
                                        "responseClass": "Bridge",
                                        "parameters": [
                                                {
                                                        "required": false,
                                                        "allowMultiple": false,
                                                        "dataType": "string",
-                                                       "allowedValues": {
-                                                               "type": "LIST",
+                                                       "allowableValues": {
+                                                               "valueType": "LIST",
                                                                "values": [
-                                                                       "two-party",
-                                                                       "multi-party",
+                                                                       "mixing",
                                                                        "holding"
                                                                ]
                                                        }
+                                               },
+                                               {
+                                                       "name": "name",
+                                                       "description": "Name to give to the bridge being created.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
                                                }
                                        ]
                                }
@@ -51,7 +58,7 @@
                                {
                                        "httpMethod": "GET",
                                        "summary": "Get bridge details.",
-                                       "nickname": "getBridge",
+                                       "nickname": "get",
                                        "responseClass": "Bridge",
                                        "parameters": [
                                                {
                                                        "allowMultiple": false,
                                                        "dataType": "string"
                                                }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Bridge not found"
+                                               }
                                        ]
                                },
                                {
                                        "httpMethod": "DELETE",
-                                       "summary": "Shut down a bridge bridge.",
+                                       "summary": "Shut down a bridge.",
                                        "notes": "If any channels are in this bridge, they will be removed and resume whatever they were doing beforehand.",
-                                       "nickname": "deleteBridge",
+                                       "nickname": "destroy",
                                        "responseClass": "void",
                                        "parameters": [
                                                {
                                                        "allowMultiple": false,
                                                        "dataType": "string"
                                                }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Bridge not found"
+                                               }
                                        ]
                                }
                        ]
                                {
                                        "httpMethod": "POST",
                                        "summary": "Add a channel to a bridge.",
-                                       "nickname": "addChannelToBridge",
+                                       "nickname": "addChannel",
                                        "responseClass": "void",
                                        "parameters": [
                                                {
                                                },
                                                {
                                                        "name": "channel",
-                                                       "description": "Channel's id",
+                                                       "description": "Ids of channels to add to bridge",
                                                        "paramType": "query",
                                                        "required": true,
                                                        "allowMultiple": true,
                                                        "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "role",
+                                                       "description": "Channel's role in the bridge",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 400,
+                                                       "reason": "Channel not found"
+                                               },
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Bridge not found"
+                                               },
+                                               {
+                                                       "code": 409,
+                                                       "reason": "Bridge not in Stasis application; Channel currently recording"
+                                               },
+                                               {
+                                                       "code": 422,
+                                                       "reason": "Channel not in Stasis application"
                                                }
                                        ]
                                }
                                {
                                        "httpMethod": "POST",
                                        "summary": "Remove a channel from a bridge.",
-                                       "nickname": "removeChannelFromBridge",
+                                       "nickname": "removeChannel",
                                        "responseClass": "void",
                                        "parameters": [
                                                {
                                                },
                                                {
                                                        "name": "channel",
-                                                       "description": "Channel's id",
+                                                       "description": "Ids of channels to remove from bridge",
                                                        "paramType": "query",
                                                        "required": true,
                                                        "allowMultiple": true,
                                                        "dataType": "string"
                                                }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 400,
+                                                       "reason": "Channel not found"
+                                               },
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Bridge not found"
+                                               },
+                                               {
+                                                       "code": 409,
+                                                       "reason": "Bridge not in Stasis application"
+                                               },
+                                               {
+                                                       "code": 422,
+                                                       "reason": "Channel not in this bridge"
+                                               }
+                                       ]
+                               }
+                       ]
+               },
+               {
+                       "path": "/bridges/{bridgeId}/moh",
+                       "description": "Play music on hold to a bridge",
+                       "operations": [
+                               {
+                                       "httpMethod": "POST",
+                                       "summary": "Play music on hold to a bridge or change the MOH class that is playing.",
+                                       "nickname": "startMoh",
+                                       "responseClass": "void",
+                                       "parameters": [
+                                               {
+                                                       "name": "bridgeId",
+                                                       "description": "Bridge's id",
+                                                       "paramType": "path",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               },
+                                               {
+                                                       "name": "mohClass",
+                                                       "description": "Channel's id",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Bridge not found"
+                                               },
+                                               {
+                                                       "code": 409,
+                                                       "reason": "Bridge not in Stasis application"
+                                               }
+                                       ]
+                               },
+                               {
+                                       "httpMethod": "DELETE",
+                                       "summary": "Stop playing music on hold to a bridge.",
+                                       "notes": "This will only stop music on hold being played via POST bridges/{bridgeId}/moh.",
+                                       "nickname": "stopMoh",
+                                       "responseClass": "void",
+                                       "parameters": [
+                                               {
+                                                       "name": "bridgeId",
+                                                       "description": "Bridge's id",
+                                                       "paramType": "path",
+                                                       "required": true,
+                                                       "allowMultiple": false,
+                                                       "dataType": "string"
+                                               }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Bridge not found"
+                                               },
+                                               {
+                                                       "code": 409,
+                                                       "reason": "Bridge not in Stasis application"
+                                               }
+                                       ]
+                               }
+                       ]
+               },
+               {
+                       "path": "/bridges/{bridgeId}/play",
+                       "description": "Play media to the participants of a bridge",
+                       "operations": [
+                               {
+                                       "httpMethod": "POST",
+                                       "summary": "Start playback of media on a bridge.",
+                                       "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": "play",
+                                       "responseClass": "Playback",
+                                       "parameters": [
+                                               {
+                                                       "name": "bridgeId",
+                                                       "description": "Bridge'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"
+                                               },
+                                               {
+                                                       "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",
+                                                       "defaultValue": 0,
+                                                       "allowableValues": {
+                                                               "valueType": "RANGE",
+                                                               "min": 0
+                                                       }
+
+                                               },
+                                               {
+                                                       "name": "skipms",
+                                                       "description": "Number of milliseconds to skip for forward/reverse operations.",
+                                                       "paramType": "query",
+                                                       "required": false,
+                                                       "allowMultiple": false,
+                                                       "dataType": "int",
+                                                       "defaultValue": 3000,
+                                                       "allowableValues": {
+                                                               "valueType": "RANGE",
+                                                               "min": 0
+                                                       }
+
+                                               }
+                                       ],
+                                       "errorResponses": [
+                                               {
+                                                       "code": 404,
+                                                       "reason": "Bridge not found"
+                                               },
+                                               {
+                                                       "code": 409,
+                                                       "reason": "Bridge not in a Stasis application"
+                                               }
                                        ]
                                }
                        ]
                                        "httpMethod": "POST",
                                        "summary": "Start a recording.",
                                        "notes": "This records the mixed audio from all channels participating in this bridge.",
-                                       "nickname": "recordBridge",
+                                       "nickname": "record",
                                        "responseClass": "LiveRecording",
                                        "parameters": [
                                                {
                                                        "dataType": "string"
                                                },
                                                {
+                                                       "name": "format",
+                                                       "description": "Format to encode audio in",
+                                                       "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
+                                                       "defaultValue": 0,
+                                                       "allowableValues": {
+                                                               "valueType": "RANGE",
+                                                               "min": 0
+                                                       }
                                                },
                                                {
                                                        "name": "maxSilenceSeconds",
                                                        "required": false,
                                                        "allowMultiple": false,
                                                        "dataType": "int",
-                                                       "defaultValue": 0
+                                                       "defaultValue": 0,
+                                                       "allowableValues": {
+                                                               "valueType": "RANGE",
+                                                               "min": 0
+                                                       }
                                                },
                                                {
-                                                       "name": "append",
-                                                       "description": "If true, and recording already exists, append to recording.",
+                                                       "name": "ifExists",
+                                                       "description": "Action to take if a recording with the same name already exists.",
                                                        "paramType": "query",
                                                        "required": false,
                                                        "allowMultiple": false,
-                                                       "dataType": "boolean",
-                                                       "defaultValue": false
+                                                       "dataType": "string",
+                                                       "defaultValue": "fail",
+                                                       "allowableValues": {
+                                                               "valueType": "LIST",
+                                                               "values": [
+                                                                       "fail",
+                                                                       "overwrite",
+                                                                       "append"
+                                                               ]
+                                                       }
                                                },
                                                {
                                                        "name": "beep",
                                                                ]
                                                        }
                                                }
-                                       ]
+                                       ],
+                    "errorResponses": [
+                        {
+                            "code": 400,
+                            "reason": "Invalid parameters"
+                        },
+                        {
+                            "code": 404,
+                            "reason": "Bridge not found"
+                        },
+                        {
+                            "code": 409,
+                            "reason": "Bridge is not in a Stasis application; A recording with the same name already exists on the system and can not be overwritten because it is in progress or ifExists=fail"
+                        },
+                                               {
+                                                       "code": 422,
+                                                       "reason": "The format specified is unknown on this system"
+                                               }
+                    ]
                                }
                        ]
                }
        "models": {
                "Bridge": {
                        "id": "Bridge",
+                       "description": "The merging of media from one or more channels.\n\nEveryone on the bridge receives the same audio.",
                        "properties": {
-                               "bridgeType": {
+                               "id": {
+                                       "type": "string",
+                                       "description": "Unique identifier for this bridge",
+                                       "required": true
+                               },
+                               "technology": {
+                                       "type": "string",
+                                       "description": "Name of the current bridging technology",
+                                       "required": true
+                               },
+                               "bridge_type": {
                                        "type": "string",
                                        "description": "Type of bridge technology",
                                        "required": true,
-                                       "allowedValues": {
-                                               "type": "LIST",
+                                       "allowableValues": {
+                                               "valueType": "LIST",
                                                "values": [
-                                                       "two-party",
-                                                       "multi-party",
+                                                       "mixing",
                                                        "holding"
                                                ]
                                        }
                                },
+                               "bridge_class": {
+                                       "type": "string",
+                                       "description": "Bridging class",
+                                       "required": true
+                               },
+                               "creator": {
+                                       "type": "string",
+                                       "description": "Entity that created the bridge",
+                                       "required": true
+                               },
+                               "name": {
+                                       "type": "string",
+                                       "description": "Name the creator gave the bridge",
+                                       "required": true
+                               },
                                "channels": {
                                        "type": "List[string]",
-                                       "description": "Id's of channels participating in this bridge",
+                                       "description": "Ids of channels participating in this bridge",
                                        "required": true
                                }
                        }