List of API nodes:
---------------------
-user/get?username=foo&domain=bar
+user/get?username=foo&domain=bar.bz
+user/get?user=user@bar.bz
Return User information, not including hardphone association.
Possible extension: allow user/get?address=foo@bar
user/list
user/list?search=foo@bar
- Return a list of users in user@domain format.
+ Return an array of users, with 'user' set to SIP-address and
+ 'displayname' set to the users Displayname.
+
If the search parameter is included, a globbing search is performed,
and only matches are listed.
-user/add_local?username=foo&domain=bar&displayname=baz&email=qux@zef.tld
- Adds a user account to both Kamailio and provisioning,
- if the username@domain is nonexistant, and the domain is local (handled by Kamailio).
- The password for the user is auto-generated.
+user/add_local?username=foo&domain=bar.bz&displayname=baz&email=qux@zef.tld
+user/add_local?user=foo@bar.bz&displayname=baz&email=qux@zef.tld
+ Adds a user account to both Kamailio and provisioning, if the
+ username@domain is nonexistant, and the domain is local (handled by
+ Kamailio). The password for the user is auto-generated.
+
Returns a full user object, the same form as user/get
user/add_remote?username=foo&domain=bar&password=S3cr3t&displayname=baz®istrar=sip.example.com
+user/add_remote?user=foo@bar.bz&password=S3cr3t&displayname=baz®istrar=sip.example.com
optionals: &r_port=5060&proxy=sipproxy.example.com&p_port=5060&authid=realfoo&dialplan=(.*)&linetext=lalala
- Adds a provisioning user for a remote SIP account. This allows locally provisioned hardphones
- to be associated with non-local SIP accounts.
- Returns a full user object, the same form as user/get
- Returns 'failed' with 'cause' = 'domain' if an attempt is made to add_remote for a local domain.
-
-user/remove?username=foo&domain=bar
- Removes user account from Kamailio, if present, and removes user from provisioning.
- Will fail if user has associated hardphones, remove phones before removing user.
- Returns 'ok' on success.
+ Adds a provisioning user for a remote SIP account. This allows locally
+ provisioned hardphones to be associated with non-local SIP accounts.
-user/gen_pw
- Test-node, generates a random password on the same form as that used
- by user/add_local. May be used with the to-be-implemented change_pw node.
+ Returns a full user object, the same form as user/get
+
+ Returns 'failed' with 'cause' = 'domain' if an attempt is made to
+ add_remote for a local domain.
user/change_pw?username=foo&domain=bar&password=baz
- Not implemented!
+user/change_pw?user=foo@bar.bz&password=baz
+ Changes the password for the given user, returns 'ok' with 'detail' as
+ a descriptive text on success. In the current implementation,
+ provisioning and kamailio passwords are handled separately, so one
+ may succeed and the other fail. As is, this permits password changes
+ of non-local provision users with minimal effort.
+
+ Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
+
+ Returns 'failed' with 'cause' = 'dbfail' if the database request
+ failed. Note that this may be because the given password was identical
+ to the old.
user/update?username=foo&domain=bar
+user/update?user=foo@bar.bz
optionals: &displayname=baz&dialplan=(.*)&linetext=lalala
Not implemented! Will only be implemented for Local users.
Remote users will have to be removed, and re-added.
+
+user/remove?username=foo&domain=bar
+user/remove?user=foo@bar.bz
+ Removes user account from Kamailio, if present, and removes user from
+ provisioning. Will fail if user has associated hardphones, remove
+ phones before removing user.
+
+ Returns 'ok' on success.
+
+user/gen_pw
+ Test-node, generates a random password on the same form as that used by
+ user/add_local. May be used with the to-be-implemented change_pw node.
+
phone/get?mac=f00ba2ba5c00
-phone/get?user=foo@bar.baz
- Returns a list of associated elements. If MAC address is given as parameter,
- a list of associated user@domain addresses is retruned. If user@domain is
- given as parameter, a list of associated mac addresses is returned.
+phone/get?user=foo@bar.bz
+phone/get?username=foo&domain=bar.bz
+ Returns a list of associated elements. If MAC address is given as
+ parameter, a list of associated user@domain addresses is retruned. If
+ user@domain is given as parameter, a list of associated mac addresses
+ is returned.
phone/list?search=f00ba2
Returns the list of registered MAC addresses. If the (optional) search
phone/add?mac=f00ba2ba5c00&username=foo&domain=bar.bz
phone/add?mac=f00ba2ba5c00&user=foo@bar.bz
- Adds a phone-to-user association to Provisioning. The user may
- be provided as 'username' and 'domain' in separate parameters,
- or as 'user' in sip-address form. The MAC address must be valid,
- in plain-hex or colon-separated form, and the user must
- match a valid user registration.
+ Adds a phone-to-user association to Provisioning. The user may be
+ provided as 'username' and 'domain' in separate parameters, or as
+ 'user' in sip-address form. The MAC address must be valid, in plain-hex
+ or colon-separated form, and the user must match a valid user
+ registration.
+
Returns the mac+user combinations on success.
phone/remove?mac=f00ba2ba5c00&username=foo&domain=bar.bz
phone/remove?mac=f00ba2ba5c00&user=foo@bar.bz
- Deletes a phone-to-user association. Required parameters
- and formats are identical to the phone/add node.
+ Deletes a phone-to-user association. Required parameters and formats
+ are identical to the phone/add node.
Returns 'ok' on success.
numbers/list?random=true
optional: limit=n
Gives a list of entries in the phone number pool.
- With no parameters, the entire (ordered) list of available numbers is returned.
- With 'search', the result of a pre-post globbing search is returned
- With 'random', a list of entries is returned unordered (random order)
- For all nodes, 'limit' may be a numeric limit of desired results.
+ With no parameters, the entire (ordered) list of available numbers is
+ returned. With 'search', the result of a pre-post globbing search is
+ returned With 'random', a list of entries is returned unordered (random
+ order) For all nodes, 'limit' may be a numeric limit of desired
+ results.
numbers/add_range?start=%2B471234&end=%2B47123456
- The start and end must have identical lead-in, and start must be less than end.
- Both numbers must be given in E164 format, remember to urlencode the plus (+ -> %2B)
- The numeric component of both will be extracted, and all numbers in the range
- will be iteratively added to the pool, including the ending number.
+ The start and end must have identical lead-in, and start must be less
+ than end. Both numbers must be given in E164 format, remember to
+ urlencode the plus (+ -> %2B). The numeric component of both will be
+ extracted, and all numbers in the range will be iteratively added to
+ the pool, including the ending number.
Returns 'ok' on success.
numbers/add?number=%2B4761123456
- Adds the given number to the pool, after verifying that the number is in
- valid E164 format, and that the number does not already exist in the pool.
+ Adds the given number to the pool, after verifying that the number is
+ in valid E164 format, and that the number does not already exist in the
+ pool.
+
Returns 'response' 'ok' and "Added <number>" in 'detail' on success.
numbers/remove?number=%2B4761123456
Removes/pulls a number from the pool.
- The number must be a valid e164 number, and must be present in the pool.
- Returns 'response' as 'ok' with 'number' set to the number that was pulled from the pool.
+ The number must be a valid e164 number, and must be present in the
+ pool.
+
+ Returns 'response' as 'ok' with 'number' set to the number that was
+ pulled from the pool.
numbers/inpool?number=%2B4761123456
Tests if the given E164 number is in the pool.
- Returns 'response' = 'ok' with 'number' = '<number>' If the number is in the pool
+ Returns 'response' = 'ok' with 'number' = '<number>' If the number is
+ in the pool
+
Returns response = 'failed' with 'cause' = 'nonexistant' if not.
alias/list
Currently not implemented
alias/add?alias_username=foo&alias_domain=bar.bz&destination=bar@qux.zx
+alias/add?alias=foo@bar.bz&destination=bar@qux.zx
Add an alias specified by alias_username and alias_domain that
points to the destination SIP-adress.
- On success, 'ok' is returned, with 'alias' and 'destination' set
- to the resulting alias and destination adresses.
+ On success, 'ok' is returned, with 'alias' and 'destination' set to the
+ resulting alias and destination adresses.
Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
resulting alias-adress or destination are invalid SIP-adresses.
- Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain
- is not a Kamailio domain.
+
+ Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
+ not a Kamailio domain.
+
Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
and the user already has an E164 alias registered.
+
Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
domain is requested, but the local subscriber does not exist.
- Returns 'failed' with 'cause' = 'exists' for aliases that already exists,
- (and aliases that overlaps SIP-accounts - not implemented).
+
+ Returns 'failed' with 'cause' = 'exists' for aliases that already
+ exists, (and aliases that overlaps SIP-accounts - not implemented).
alias/remove?alias_username=foo&alias_domain=bar.bz
+alias/remove?alias=foo@bar.bz
Removes the alias given by alias_username and alias_domain.
Returns 'ok' with the removed alias adress as 'alias' on success
- Returns 'failed' with 'cause' = 'nonexistant' it the alias does not exists.
- Returns 'invalid' with 'cause' = 'address' if the given alias is not a valid SIP adress.
+
+ Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
+ exists.
+
+ Returns 'invalid' with 'cause' = 'address' if the given alias is not a
+ valid SIP adress.
TODO list:
---------------------
Planned, but not implemented nodes/functions:
- user/change_pw?username=foo&domain=bar&password=baz
user/update?username=foo&domain=bar
alias/list
alias/user?destination=foo@bar.bz
Add collision prevention for users, make sure that no user can be added when the user
address would overlap/collide with a valid alias-address
+Change all GET to POST
+
+Implement test-tool for POST-based communication ;)
+
+Improve robustness of change_pw: fetch old password for rollback/testing.
+
+Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec
git.defcon.no / hermes / commitdiff