ARI event type filtering
[asterisk/asterisk.git] / rest-api / api-docs / applications.json
1 {
2         "_copyright": "Copyright (C) 2013, Digium, Inc.",
3         "_author": "David M. Lee, II <dlee@digium.com>",
4         "_svn_revision": "$Revision$",
5         "apiVersion": "2.0.0",
6         "swaggerVersion": "1.1",
7         "basePath": "http://localhost:8088/ari",
8         "resourcePath": "/api-docs/applications.{format}",
9         "apis": [
10                 {
11                         "path": "/applications",
12                         "description": "Stasis applications",
13                         "operations": [
14                                 {
15                                         "httpMethod": "GET",
16                                         "summary": "List all applications.",
17                                         "nickname": "list",
18                                         "responseClass": "List[Application]"
19                                 }
20                         ]
21                 },
22                 {
23                         "path": "/applications/{applicationName}",
24                         "description": "Stasis application",
25                         "operations": [
26                                 {
27                                         "httpMethod": "GET",
28                                         "summary": "Get details of an application.",
29                                         "nickname": "get",
30                                         "responseClass": "Application",
31                                         "parameters": [
32                                                 {
33                                                         "name": "applicationName",
34                                                         "description": "Application's name",
35                                                         "paramType": "path",
36                                                         "required": true,
37                                                         "allowMultiple": false,
38                                                         "dataType": "string"
39                                                 }
40                                         ],
41                                         "errorResponses": [
42                                                 {
43                                                         "code": 404,
44                                                         "reason": "Application does not exist."
45                                                 }
46                                         ]
47                                 }
48                         ]
49                 },
50                 {
51                         "path": "/applications/{applicationName}/subscription",
52                         "description": "Stasis application",
53                         "operations": [
54                                 {
55                                         "httpMethod": "POST",
56                                         "summary": "Subscribe an application to a event source.",
57                                         "notes": "Returns the state of the application after the subscriptions have changed",
58                                         "nickname": "subscribe",
59                                         "responseClass": "Application",
60                                         "parameters": [
61                                                 {
62                                                         "name": "applicationName",
63                                                         "description": "Application's name",
64                                                         "paramType": "path",
65                                                         "required": true,
66                                                         "allowMultiple": false,
67                                                         "dataType": "string"
68                                                 },
69                                                 {
70                                                         "name": "eventSource",
71                                                         "description": "URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}[/{resource}], deviceState:{deviceName}",
72                                                         "paramType": "query",
73                                                         "required": true,
74                                                         "allowMultiple": true,
75                                                         "dataType": "string"
76                                                 }
77                                         ],
78                                         "errorResponses": [
79                                                 {
80                                                         "code": 400,
81                                                         "reason": "Missing parameter."
82                                                 },
83                                                 {
84                                                         "code": 404,
85                                                         "reason": "Application does not exist."
86                                                 },
87                                                 {
88                                                         "code": 422,
89                                                         "reason": "Event source does not exist."
90                                                 }
91                                         ]
92                                 },
93                                 {
94                                         "httpMethod": "DELETE",
95                                         "summary": "Unsubscribe an application from an event source.",
96                                         "notes": "Returns the state of the application after the subscriptions have changed",
97                                         "nickname": "unsubscribe",
98                                         "responseClass": "Application",
99                                         "parameters": [
100                                                 {
101                                                         "name": "applicationName",
102                                                         "description": "Application's name",
103                                                         "paramType": "path",
104                                                         "required": true,
105                                                         "allowMultiple": false,
106                                                         "dataType": "string"
107                                                 },
108                                                 {
109                                                         "name": "eventSource",
110                                                         "description": "URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}[/{resource}], deviceState:{deviceName}",
111                                                         "paramType": "query",
112                                                         "required": true,
113                                                         "allowMultiple": true,
114                                                         "dataType": "string"
115                                                 }
116                                         ],
117                                         "errorResponses": [
118                                                 {
119                                                         "code": 400,
120                                                         "reason": "Missing parameter; event source scheme not recognized."
121                                                 },
122                                                 {
123                                                         "code": 404,
124                                                         "reason": "Application does not exist."
125                                                 },
126                                                 {
127                                                         "code": 409,
128                                                         "reason": "Application not subscribed to event source."
129                                                 },
130                                                 {
131                                                         "code": 422,
132                                                         "reason": "Event source does not exist."
133                                                 }
134                                         ]
135                                 }
136                         ]
137                 },
138                 {
139                         "path": "/applications/{applicationName}/eventFilter",
140                         "description": "Stasis application",
141                         "operations": [
142                                 {
143                                         "httpMethod": "PUT",
144                                         "summary": "Filter application events types.",
145                                         "notes": "Allowed and/or disallowed event type filtering can be done. The body (parameter) should specify a JSON key/value object that describes the type of event filtering needed. One, or both of the following keys can be designated:<br /><br />\"allowed\" - Specifies an allowed list of event types<br />\"disallowed\" - Specifies a disallowed list of event types<br /><br />Further, each of those key's value should be a JSON array that holds zero, or more JSON key/value objects. Each of these objects must contain the following key with an associated value:<br /><br />\"type\" - The type name of the event to filter<br /><br />The value must be the string name (case sensitive) of the event type that needs filtering. For example:<br /><br />{ \"allowed\": [ { \"type\": \"StasisStart\" }, { \"type\": \"StasisEnd\" } ] }<br /><br />As this specifies only an allowed list, then only those two event type messages are sent to the application. No other event messages are sent.<br /><br />The following rules apply:<br /><br />* If the body is empty, both the allowed and disallowed filters are set empty.<br />* If both list types are given then both are set to their respective values (note, specifying an empty array for a given type sets that type to empty).<br />* If only one list type is given then only that type is set. The other type is not updated.<br />* An empty \"allowed\" list means all events are allowed.<br />* An empty \"disallowed\" list means no events are disallowed.<br />* Disallowed events take precedence over allowed events if the event type is specified in both lists.",
146                                         "nickname": "filter",
147                                         "responseClass": "Application",
148                                         "parameters": [
149                                                 {
150                                                         "name": "applicationName",
151                                                         "description": "Application's name",
152                                                         "paramType": "path",
153                                                         "required": true,
154                                                         "allowMultiple": false,
155                                                         "dataType": "string"
156                                                 },
157                                                 {
158                                                         "name": "filter",
159                                                         "description": "Specify which event types to allow/disallow",
160                                                         "paramType": "body",
161                                                         "required": false,
162                                                         "dataType": "object",
163                                                         "allowMultiple": false
164                                                 }
165                                         ],
166                                         "errorResponses": [
167                                                 {
168                                                         "code": 400,
169                                                         "reason": "Bad request."
170                                                 },
171                                                 {
172                                                         "code": 404,
173                                                         "reason": "Application does not exist."
174                                                 }
175                                         ]
176                                 }
177                         ]
178                 }
179         ],
180         "models": {
181                 "Application": {
182                         "id": "Application",
183                         "description": "Details of a Stasis application",
184                         "properties": {
185                                 "name": {
186                                         "type": "string",
187                                         "description": "Name of this application",
188                                         "required": true
189                                 },
190                                 "channel_ids": {
191                                         "type": "List[string]",
192                                         "description": "Id's for channels subscribed to.",
193                                         "required": true
194                                 },
195                                 "bridge_ids": {
196                                         "type": "List[string]",
197                                         "description": "Id's for bridges subscribed to.",
198                                         "required": true
199                                 },
200                                 "endpoint_ids": {
201                                         "type": "List[string]",
202                                         "description": "{tech}/{resource} for endpoints subscribed to.",
203                                         "required": true
204                                 },
205                                 "device_names": {
206                                         "type": "List[string]",
207                                         "description": "Names of the devices subscribed to.",
208                                         "required": true
209                                 },
210                                 "events_allowed": {
211                                         "type": "List[object]",
212                                         "description": "Event types sent to the application.",
213                                         "required": true
214                                 },
215                                 "events_disallowed": {
216                                         "type": "List[object]",
217                                         "description": "Event types not sent to the application.",
218                                         "required": true
219                                 }
220                         }
221                 }
222         }
223 }