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"...
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
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.
25 If the search parameter is included, a globbing search is performed,
26 and only matches are listed.
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.
34 Returns a full user object, the same form as user/get
36 user/add_remote?username=foo&domain=bar&password=S3cr3t&displayname=baz®istrar=sip.example.com
37 user/add_remote?user=foo@bar.bz&password=S3cr3t&displayname=baz®istrar=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.
42 Returns a full user object, the same form as user/get
44 Returns 'failed' with 'cause' = 'domain' if an attempt is made to
45 add_remote for a local domain.
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.
55 Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
57 Returns 'failed' with 'cause' = 'dbfail' if the database request
58 failed. Note that this may be because the given password was identical
61 user/update?username=foo&domain=bar
62 user/update?user=foo@bar.bz
63 optionals: &displayname=baz&dialplan=(.*)&linetext=lalala
64 Not implemented! Will only be implemented for Local users.
65 Remote users will have to be removed, and re-added.
68 user/remove?username=foo&domain=bar
69 user/remove?user=foo@bar.bz
70 Removes user account from Kamailio, if present, and removes user from
71 provisioning. Will fail if user has associated hardphones, remove
72 phones before removing user.
74 Returns 'ok' on success.
77 Test-node, generates a random password on the same form as that used by
78 user/add_local. May be used with the to-be-implemented change_pw node.
80 phone/get?mac=f00ba2ba5c00
81 phone/get?user=foo@bar.bz
82 phone/get?username=foo&domain=bar.bz
83 Returns a list of associated elements. If MAC address is given as
84 parameter, a list of associated user@domain addresses is retruned. If
85 user@domain is given as parameter, a list of associated mac addresses
88 phone/list?search=f00ba2
89 Returns the list of registered MAC addresses. If the (optional) search
90 parameter is included, the list is the result of a globbing search,
91 a subset matching on the MAC addresses.
93 phone/add?mac=f00ba2ba5c00&username=foo&domain=bar.bz
94 phone/add?mac=f00ba2ba5c00&user=foo@bar.bz
95 Adds a phone-to-user association to Provisioning. The user may be
96 provided as 'username' and 'domain' in separate parameters, or as
97 'user' in sip-address form. The MAC address must be valid, in plain-hex
98 or colon-separated form, and the user must match a valid user
101 Returns the mac+user combinations on success.
103 phone/remove?mac=f00ba2ba5c00&username=foo&domain=bar.bz
104 phone/remove?mac=f00ba2ba5c00&user=foo@bar.bz
105 Deletes a phone-to-user association. Required parameters and formats
106 are identical to the phone/add node.
107 Returns 'ok' on success.
111 numbers/list?search=1234
112 numbers/list?random=true
114 Gives a list of entries in the phone number pool.
115 With no parameters, the entire (ordered) list of available numbers is
116 returned. With 'search', the result of a pre-post globbing search is
117 returned With 'random', a list of entries is returned unordered (random
118 order) For all nodes, 'limit' may be a numeric limit of desired
121 numbers/add_range?start=%2B471234&end=%2B47123456
122 The start and end must have identical lead-in, and start must be less
123 than end. Both numbers must be given in E164 format, remember to
124 urlencode the plus (+ -> %2B). The numeric component of both will be
125 extracted, and all numbers in the range will be iteratively added to
126 the pool, including the ending number.
127 Returns 'ok' on success.
129 numbers/add?number=%2B4761123456
130 Adds the given number to the pool, after verifying that the number is
131 in valid E164 format, and that the number does not already exist in the
134 Returns 'response' 'ok' and "Added <number>" in 'detail' on success.
136 numbers/remove?number=%2B4761123456
137 Removes/pulls a number from the pool.
138 The number must be a valid e164 number, and must be present in the
141 Returns 'response' as 'ok' with 'number' set to the number that was
142 pulled from the pool.
144 numbers/inpool?number=%2B4761123456
145 Tests if the given E164 number is in the pool.
146 Returns 'response' = 'ok' with 'number' = '<number>' If the number is
149 Returns response = 'failed' with 'cause' = 'nonexistant' if not.
152 alias/list?destination=foo@bar.bz
153 alias/list?destination=foo@bar.bz&e164=true
154 alias/list?alias=foo@bar.bz
155 Currently not implemented
157 alias/add?alias_username=foo&alias_domain=bar.bz&destination=bar@qux.zx
158 alias/add?alias=foo@bar.bz&destination=bar@qux.zx
159 Add an alias specified by alias_username and alias_domain that
160 points to the destination SIP-adress.
162 On success, 'ok' is returned, with 'alias' and 'destination' set to the
163 resulting alias and destination adresses.
165 Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
166 resulting alias-adress or destination are invalid SIP-adresses.
168 Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
169 not a Kamailio domain.
171 Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
172 and the user already has an E164 alias registered.
174 Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
175 domain is requested, but the local subscriber does not exist.
177 Returns 'failed' with 'cause' = 'exists' for aliases that already
178 exists, (and aliases that overlaps SIP-accounts - not implemented).
181 alias/remove?alias_username=foo&alias_domain=bar.bz
182 alias/remove?alias=foo@bar.bz
183 Removes the alias given by alias_username and alias_domain.
185 Returns 'ok' with the removed alias adress as 'alias' on success
187 Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
190 Returns 'invalid' with 'cause' = 'address' if the given alias is not a
194 ---------------------
195 Planned, but not implemented nodes/functions:
196 user/update?username=foo&domain=bar
198 alias/user?destination=foo@bar.bz
200 authentication-mechanism :)
202 Add collision prevention for users, make sure that no user can be added when the user
203 address would overlap/collide with a valid alias-address
205 Change all GET to POST
207 Implement test-tool for POST-based communication ;)
209 Improve robustness of change_pw: fetch old password for rollback/testing.
211 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec