From: jonl <jonl@sippbx.hig.no> Date: Mon, 16 Jan 2012 18:27:01 +0000 (+0100) Subject: Updated to reflect changes to user/list and user/change_pw. Reformatted for printing X-Git-Url: https://git.defcon.no/?a=commitdiff_plain;h=13e9924ec70d6210835498448935278c690b6094;p=hermes Updated to reflect changes to user/list and user/change_pw. Reformatted for printing --- diff --git a/api-nodes.txt b/api-nodes.txt index 1a26ef8..b01058a 100644 --- a/api-nodes.txt +++ b/api-nodes.txt @@ -12,51 +12,78 @@ a 'response' element. The 'response' may be set to: 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 @@ -65,17 +92,18 @@ phone/list?search=f00ba2 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. @@ -84,31 +112,40 @@ numbers/list?search=1234 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 @@ -118,35 +155,44 @@ alias/list?alias=foo@bar.bz 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 @@ -156,3 +202,10 @@ authentication-mechanism :) 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