All API nodes currently use GET requests for all parameters. All API nodes return JSON data, and all results will contain a 'response' element. The 'response' may be set to: * 'ok' on success. Further contents depend on the node requested. * 'invalid' on invalid requests. A 'cause' element should give a keyword denoting what was invalid about the request... * 'failed' on simple failure. A 'cause' element is supplied, with a failure-keyword (e.g. 'nonexistant', 'inuse', 'dbfail'). A final 'detail' is commonly included, with a verbose desctiption. * 'error' on critical failure. Regard this as a soft form of "500 server error"... List of API nodes: --------------------- user/get?username=foo&domain=bar 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. 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. 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 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. 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. user/change_pw?username=foo&domain=bar&password=baz Not implemented! user/update?username=foo&domain=bar 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. 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/list?search=f00ba2 Returns the list of registered MAC addresses. If the (optional) search parameter is included, the list is the result of a globbing search, a subset matching on the MAC addresses. 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. 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. Returns 'ok' on success. numbers/list 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. 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. 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. Returns 'response' 'ok' and "Added " 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. numbers/inpool?number=%2B4761123456 Tests if the given E164 number is in the pool. Returns 'response' = 'ok' with 'number' = '' If the number is in the pool Returns response = 'failed' with 'cause' = 'nonexistant' if not. alias/list alias/list?destination=foo@bar.bz alias/list?destination=foo@bar.bz&e164=true alias/list?alias=foo@bar.bz Currently not implemented alias/add?alias_username=foo&alias_domain=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. 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' = '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). alias/remove?alias_username=foo&alias_domain=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. 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 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