]> git.defcon.no Git - hermes/blob - doc/api-nodes.txt
Merge http://git.defcon.no/hermes
[hermes] / doc / api-nodes.txt
1 All API nodes currently use GET requests for all parameters.
2 All API nodes return JSON data, and all results will contain
3 a 'response' element. The 'response' may be set to:
4 * 'ok' on success. Further contents depend on the node requested.
5 * 'invalid' on invalid requests. A 'cause' element should give a
6 keyword denoting what was invalid about the request...
7 * 'failed' on simple failure. A 'cause' element is supplied, with a
8 failure-keyword (e.g. 'nonexistant', 'inuse', 'dbfail').
9 A final 'detail' is commonly included, with a verbose desctiption.
10 * 'error' on critical failure. Regard this as a soft form of "500 server error"...
11
12 List of API nodes:
13 ---------------------
14
15 user/get?username=foo&domain=bar.bz
16 user/get?user=user@bar.bz
17 Return User information, not including hardphone association.
18 Possible extension: allow user/get?address=foo@bar
19
20 user/list
21 user/list?search=foo@bar
22 Return an array of users, with 'user' set to SIP-address and
23 'displayname' set to the users Displayname.
24
25 If the search parameter is included, a globbing search is performed,
26 and only matches are listed.
27
28 user/add_local?username=foo&domain=bar.bz&displayname=baz&email=qux@zef.tld
29 user/add_local?user=foo@bar.bz&displayname=baz&email=qux@zef.tld
30 Adds a user account to both Kamailio and provisioning, if the
31 username@domain is nonexistant, and the domain is local (handled by
32 Kamailio). The password for the user is auto-generated.
33
34 Returns a full user object, the same form as user/get
35
36 user/add_remote?username=foo&domain=bar&password=S3cr3t&displayname=baz&registrar=sip.example.com
37 user/add_remote?user=foo@bar.bz&password=S3cr3t&displayname=baz&registrar=sip.example.com
38 optionals: &r_port=5060&proxy=sipproxy.example.com&p_port=5060&authid=realfoo&dialplan=(.*)&linetext=lalala
39 Adds a provisioning user for a remote SIP account. This allows locally
40 provisioned hardphones to be associated with non-local SIP accounts.
41
42 Returns a full user object, the same form as user/get
43
44 Returns 'failed' with 'cause' = 'domain' if an attempt is made to
45 add_remote for a local domain.
46
47 user/change_pw?username=foo&domain=bar&password=baz
48 user/change_pw?user=foo@bar.bz&password=baz
49 Changes the password for the given user, returns 'ok' with 'detail' as
50 a descriptive text on success. In the current implementation,
51 provisioning and kamailio passwords are handled separately, so one
52 may succeed and the other fail. As is, this permits password changes
53 of non-local provision users with minimal effort.
54
55 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
56
57 Returns 'failed' with 'cause' = 'dbfail' if the database request
58 failed. Note that this may be because the given password was identical
59 to the old.
60
61 user/update?username=foo&domain=bar
62 user/update?user=foo@bar.bz
63 optionals: &displayname=baz&dialplan=(.*)&linetext=lalala&email=foo@bar.baz
64 Not implemented! Will only be implemented for Local users.
65 Remote users will have to be removed, and re-added.
66
67 user/change_email?username=foo&domain=bar&email=user@example.com
68 user/change_email?user=foo@bar.bz&email=user@example.com
69 Changes the email address for the given user, returns 'ok' with
70 'user' set to the requested username and 'email' set to the
71 email address. This only applies to kamailio local users.
72
73 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
74
75 Returns 'failed' with 'cause' = 'dbfail' if the database request
76 failed. Note that this may be because the given password was identical
77 to the old.
78
79
80 user/remove?username=foo&domain=bar
81 user/remove?user=foo@bar.bz
82 Removes user account from Kamailio, if present, and removes user from
83 provisioning.
84
85 Will fail if user has associated hardphones, remove phones before
86 removing user.
87
88 TODO: Should fail if user has associated aliases. Remove aliases before
89 removing user.
90
91 Returns 'ok' on success.
92
93 user/gen_pw
94 Generates a random password on the same form as that used by
95 user/add_local.
96
97 Return is always a password in plain text, with no formatting.
98
99 phone/get?mac=f00ba2ba5c00
100 phone/get?user=foo@bar.bz
101 phone/get?username=foo&domain=bar.bz
102 Returns a list of associated elements. If MAC address is given as
103 parameter, a list of associated user@domain addresses is retruned. If
104 user@domain is given as parameter, a list of associated mac addresses
105 is returned.
106
107 phone/list?search=f00ba2
108 Returns the list of registered MAC addresses. If the (optional) search
109 parameter is included, the list is the result of a globbing search,
110 a subset matching on the MAC addresses.
111
112 phone/add?mac=f00ba2ba5c00&username=foo&domain=bar.bz
113 phone/add?mac=f00ba2ba5c00&user=foo@bar.bz
114 Adds a phone-to-user association to Provisioning. The user may be
115 provided as 'username' and 'domain' in separate parameters, or as
116 'user' in sip-address form. The MAC address must be valid, in plain-hex
117 or colon-separated form, and the user must match a valid user
118 registration.
119
120 Returns the mac+user combinations on success.
121
122 phone/remove?mac=f00ba2ba5c00&username=foo&domain=bar.bz
123 phone/remove?mac=f00ba2ba5c00&user=foo@bar.bz
124 Deletes a phone-to-user association. Required parameters and formats
125 are identical to the phone/add node.
126 Returns 'ok' on success.
127
128
129 numbers/list
130 numbers/list?search=1234
131 numbers/list?random=true
132 optional: limit=n
133 Gives a list of entries in the phone number pool.
134 With no parameters, the entire (ordered) list of available numbers is
135 returned. With 'search', the result of a pre-post globbing search is
136 returned With 'random', a list of entries is returned unordered (random
137 order) For all nodes, 'limit' may be a numeric limit of desired
138 results.
139
140 numbers/add_range?start=%2B471234&end=%2B47123456
141 The start and end must have identical lead-in, and start must be less
142 than end. Both numbers must be given in E164 format, remember to
143 urlencode the plus (+ -> %2B). The numeric component of both will be
144 extracted, and all numbers in the range will be iteratively added to
145 the pool, including the ending number.
146 Returns 'ok' on success.
147
148 numbers/add?number=%2B4761123456
149 Adds the given number to the pool, after verifying that the number is
150 in valid E164 format, and that the number does not already exist in the
151 pool.
152
153 Returns 'response' 'ok' and "Added <number>" in 'detail' on success.
154
155 numbers/remove?number=%2B4761123456
156 Removes/pulls a number from the pool.
157 The number must be a valid e164 number, and must be present in the
158 pool.
159
160 Returns 'response' as 'ok' with 'number' set to the number that was
161 pulled from the pool.
162
163 numbers/inpool?number=%2B4761123456
164 Tests if the given E164 number is in the pool.
165 Returns 'response' = 'ok' with 'number' = '<number>' If the number is
166 in the pool
167
168 Returns response = 'failed' with 'cause' = 'nonexistant' if not.
169
170 alias/list
171 alias/list?destination=foo@bar.bz
172 alias/list?destination=foo@bar.bz&e164=true
173 alias/list?alias=foo@bar.bz
174 With no parameters, this will return all defined aliases (potentially a
175 huge list). With the destination parameter set, only aliases dfor that
176 destination will be listed, and with the e164 option set to true, only
177 an e164 alias will be returned (if one/it exists). The alias parameter
178 gives the same behaviour, butr looks up an alias address instead of the
179 destination. The e164 option is not valid for the alias search
180 (naturally).
181
182 Returns 'ok' on success, with an array of 'destination' and 'alias'
183 pairs.
184
185 Returns 'ok' with an empty array if the search gave no results.
186
187 Returns 'ok' with an empty array if the database search fails.
188
189 Returns 'failed' with 'cause' = 'invalid' on invalid SIP addresses.
190
191 alias/add?alias_username=foo&alias_domain=bar.bz&destination=bar@qux.zx
192 alias/add?alias=foo@bar.bz&destination=bar@qux.zx
193 Add an alias specified by alias_username and alias_domain that
194 points to the destination SIP-adress.
195
196 On success, 'ok' is returned, with 'alias' and 'destination' set to the
197 resulting alias and destination adresses.
198
199 Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
200 resulting alias-adress or destination are invalid SIP-adresses.
201
202 Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
203 not a Kamailio domain.
204
205 Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
206 and the user already has an E164 alias registered.
207
208 Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
209 domain is requested, but the local subscriber does not exist.
210
211 Returns 'failed' with 'cause' = 'exists' for aliases that already
212 exists, (and aliases that overlaps SIP-accounts - not implemented).
213
214
215 alias/remove?alias_username=foo&alias_domain=bar.bz
216 alias/remove?alias=foo@bar.bz
217 Removes the alias given by alias_username and alias_domain.
218
219 Returns 'ok' with the removed alias adress as 'alias' on success
220
221 Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
222 exists.
223
224 Returns 'invalid' with 'cause' = 'address' if the given alias is not a
225 valid SIP adress.
226
227 BUGS:
228 ---------------------
229
230 api/alias/list?destination=foo@bar.bz&e164=true
231 should return an empty array, returns false
232
233 TODO list:
234 ---------------------
235
236 Add a node to test a destination (pre-flight testing of user/add and alias/add)
237
238 Read list of kamailio domains (domains/list ?) RW?
239 Default server-settings for domains (domains/server ? ) (registrar, proxy, ports...) RW.
240 Permissions! (user/permissions?user=...)
241
242 authentication-mechanism :)
243
244 Add collision prevention for users, make sure that no user can be added when the user
245 address would overlap/collide with a valid alias-address
246
247 Change all GET to POST
248
249 Implement test-tool for POST-based communication ;)
250
251 Improve robustness of change_pw: fetch old password for rollback/testing.
252
253 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec