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.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 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.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/change_pw?username=foo&domain=bar&password=baz 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&email=foo@bar.baz Not implemented! Will only be implemented for Local users. Remote users will have to be removed, and re-added. user/change_email?username=foo&domain=bar&email=user@example.com user/change_email?user=foo@bar.bz&email=user@example.com Changes the email address for the given user, returns 'ok' with 'user' set to the requested username and 'email' set to the email address. This only applies to kamailio local users. 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/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. TODO: Should fail if user has associated aliases. Remove aliases before removing user. Returns 'ok' on success. user/available?username=foo&domain=bar user/available?user=foo@bar.bz Tests an address to see if it is available. Returns 'ok' with 'cause' = 'nonexistant' if the address is available. Returns 'failed' with 'cause' = 'exists' if the address is in use. user/gen_pw Generates a random password on the same form as that used by user/add_local. Return is always a password in plain text, with no formatting. phone/get?mac=f00ba2ba5c00 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 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 With no parameters, this will return all defined aliases (potentially a huge list). With the destination parameter set, only aliases dfor that destination will be listed, and with the e164 option set to true, only an e164 alias will be returned (if one/it exists). The alias parameter gives the same behaviour, butr looks up an alias address instead of the destination. The e164 option is not valid for the alias search (naturally). Returns 'ok' on success, with an array of 'destination' and 'alias' pairs. Returns 'ok' with an empty array if the search gave no results. Returns 'ok' with an empty array if the database search fails. Returns 'failed' with 'cause' = 'invalid' on invalid SIP addresses. 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. 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 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. domain/list Returns a list of configured and valid domains. May return an empty list if no domains are configured for kamailio. No node is provided to add domains, this is not a task for Hermes, but a kamailio configuration task. Returns 'failed' on database errors. domain/get_servers?domain=bar.bz Provides the default registrar/proxy/provisioning server information for the given domain. Returns 'ok' with 'servers' set to a kvp-set on success, containing: 'registrar', 'r_port', 'proxy', 'p_port', 'prov_url'. Returns 'failed' with 'cause' = 'nonexistant' if lookup of data for given domain results in an empty set (not configured). domain/set_servers?domain=bar.bz®istrar=server.bar.bz&r_port=5060&proxy=proxy.bar.bz&p_port=5060&prov_url=http://server.bar.bz/hermes/prov Sets the server data for the given domain. All of these parameters are required: 'domain', 'registrar', 'r_port', 'proxy', 'p_port', 'prov_url'. If no defaul server data is defined, the configuration is added. If server configuration existed, the default data is updated. Returns 'ok' with 'servers' set as domain/get_servers on success. Returns 'failed' with 'cause' set to 'cause' set to 'parameters' if one of these is true: * Missing parameters * One or more NULL/empty parameters * Non-numeric values for port-numbers. If you need to determine which of these triggered, the 'description' contains a text describing the actual fail. Return 'failed' with 'cause' = 'error' on database failure. BUGS: --------------------- api/alias/list?destination=foo@bar.bz&e164=true should return an empty array, returns false TODO list: --------------------- Add a node to test a destination (pre-flight testing of user/add and alias/add) Read list of kamailio domains (domains/list ?) RW? Default server-settings for domains (domains/server ? ) (registrar, proxy, ports...) RW. Permissions! (user/permissions?user=...) authentication-mechanism :) 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