git.defcon.no Git - hermes/blob - doc/api-nodes.txt

   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"...
  11
  12 List of API nodes:
  13 ---------------------
  14
  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
  19
  20 user/list
  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.
  24
  25         If the search parameter is included, a globbing search is performed,
  26         and only matches are listed.
  27
  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.
  33
  34         Returns a full user object, the same form as user/get
  35
  36 user/add_remote?username=foo&domain=bar&password=S3cr3t&displayname=baz&registrar=sip.example.com
  37 user/add_remote?user=foo@bar.bz&password=S3cr3t&displayname=baz&registrar=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.
  41
  42         Returns a full user object, the same form as user/get
  43
  44         Returns 'failed' with  'cause' = 'domain' if an attempt is made to
  45         add_remote for a local domain.
  46
  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.
  54
  55         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
  56
  57         Returns 'failed' with 'cause' = 'dbfail' if the database request
  58         failed. Note that this may be because the given password was identical
  59         to the old.
  60
  61 user/update?username=foo&domain=bar
  62 user/update?user=foo@bar.bz
  63   optionals: &displayname=baz&dialplan=(.*)&linetext=lalala&email=foo@bar.baz
  64         Not implemented! Will only be implemented for Local users.
  65         Remote users will have to be removed, and re-added.
  66
  67 user/change_email?username=foo&domain=bar&email=user@example.com
  68 user/change_email?user=foo@bar.bz&email=user@example.com
  69         Changes the email address for the given user, returns 'ok' with
  70         'user' set to the requested username and 'email' set to the
  71         email address.  This only applies to kamailio local users.
  72
  73         Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
  74
  75         Returns 'failed' with 'cause' = 'dbfail' if the database request
  76         failed. Note that this may be because the given password was identical
  77         to the old.
  78
  79
  80 user/remove?username=foo&domain=bar
  81 user/remove?user=foo@bar.bz
  82         Removes user account from Kamailio, if present, and removes user from
  83         provisioning.
  84
  85         Will fail if user has associated hardphones, remove phones before
  86         removing user.
  87
  88         TODO: Should fail if user has associated aliases. Remove aliases before
  89         removing user.
  90
  91         Returns 'ok' on success.
  92
  93 user/available?username=foo&domain=bar
  94 user/available?user=foo@bar.bz
  95         Tests an address to see if it is available.
  96
  97         Returns 'ok' with 'cause' = 'nonexistant' if the address is available.
  98
  99         Returns 'failed' with 'cause' = 'exists' if the address is in use.
 100
 101 user/gen_pw
 102         Generates a random password on the same form as that used by
 103         user/add_local.
 104
 105         Return is always a password in plain text, with no formatting.
 106
 107 phone/get?mac=f00ba2ba5c00
 108 phone/get?user=foo@bar.bz
 109 phone/get?username=foo&domain=bar.bz
 110         Returns a list of associated elements. If MAC address is given as
 111         parameter, a list of associated user@domain addresses is retruned. If
 112         user@domain is given as parameter, a list of associated mac addresses
 113         is returned.
 114
 115 phone/list?search=f00ba2
 116         Returns the list of registered MAC addresses. If the (optional) search
 117         parameter is included, the list is the result of a globbing search,
 118         a subset matching on the MAC addresses.
 119
 120 phone/add?mac=f00ba2ba5c00&username=foo&domain=bar.bz
 121 phone/add?mac=f00ba2ba5c00&user=foo@bar.bz
 122         Adds a phone-to-user association to Provisioning. The user may be
 123         provided as 'username' and 'domain' in separate parameters, or as
 124         'user' in sip-address form. The MAC address must be valid, in plain-hex
 125         or colon-separated form, and the user must match a valid user
 126         registration.
 127
 128         Returns the mac+user combinations on success.
 129
 130 phone/remove?mac=f00ba2ba5c00&username=foo&domain=bar.bz
 131 phone/remove?mac=f00ba2ba5c00&user=foo@bar.bz
 132         Deletes a phone-to-user association. Required parameters and formats
 133         are identical to the phone/add node.
 134         Returns 'ok' on success.
 135
 136
 137 numbers/list
 138 numbers/list?search=1234
 139 numbers/list?random=true
 140   optional: limit=n
 141         Gives a list of entries in the phone number pool.
 142         With no parameters, the entire (ordered) list of available numbers is
 143         returned.  With 'search', the result of a pre-post globbing search is
 144         returned With 'random', a list of entries is returned unordered (random
 145         order) For all nodes, 'limit' may be a numeric limit of desired
 146         results.
 147
 148 numbers/add_range?start=%2B471234&end=%2B47123456
 149         The start and end must have identical lead-in, and start must be less
 150         than end.  Both numbers must be given in E164 format, remember to
 151         urlencode the plus (+ -> %2B). The numeric component of both will be
 152         extracted, and all numbers in the range will be iteratively added to
 153         the pool, including the ending number.
 154         Returns 'ok' on success.
 155
 156 numbers/add?number=%2B4761123456
 157         Adds the given number to the pool, after verifying that the number is
 158         in valid E164 format, and that the number does not already exist in the
 159         pool.
 160
 161         Returns 'response' 'ok' and "Added <number>" in 'detail' on success.
 162
 163 numbers/remove?number=%2B4761123456
 164         Removes/pulls a number from the pool.
 165         The number must be a valid e164 number, and must be present in the
 166         pool.
 167
 168         Returns 'response' as 'ok' with 'number' set to the number that was
 169         pulled from the pool.
 170
 171 numbers/inpool?number=%2B4761123456
 172         Tests if the given E164 number is in the pool.
 173         Returns 'response' = 'ok' with 'number' = '<number>' If the number is
 174         in the pool
 175
 176         Returns response = 'failed' with 'cause' = 'nonexistant' if not.
 177
 178 alias/list
 179 alias/list?destination=foo@bar.bz
 180 alias/list?destination=foo@bar.bz&e164=true
 181 alias/list?alias=foo@bar.bz
 182         With no parameters, this will return all defined aliases (potentially a
 183         huge list). With the destination parameter set, only aliases dfor that
 184         destination will be listed, and with the e164 option set to true, only
 185         an e164 alias will be returned (if one/it exists). The alias parameter
 186         gives the same behaviour, butr looks up an alias address instead of the
 187         destination. The e164 option is not valid for the alias search
 188         (naturally).
 189
 190         Returns 'ok' on success, with an array of 'destination' and 'alias'
 191         pairs.
 192
 193         Returns 'ok' with an empty array if the search gave no results.
 194
 195         Returns 'ok' with an empty array if the database search fails.
 196
 197         Returns 'failed' with 'cause' = 'invalid' on invalid SIP addresses.
 198
 199 alias/add?alias_username=foo&alias_domain=bar.bz&destination=bar@qux.zx
 200 alias/add?alias=foo@bar.bz&destination=bar@qux.zx
 201         Add an alias specified by alias_username and alias_domain that
 202         points to the destination SIP-adress.
 203
 204         On success, 'ok' is returned, with 'alias' and 'destination' set to the
 205         resulting alias and destination adresses.
 206
 207         Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
 208         resulting alias-adress or destination are invalid SIP-adresses.
 209
 210         Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
 211         not a Kamailio domain.
 212
 213         Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
 214         and the user already has an E164 alias registered.
 215
 216         Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
 217         domain is requested, but the local subscriber does not exist.
 218
 219         Returns 'failed' with 'cause' = 'exists' for aliases that already
 220         exists, (and aliases that overlaps SIP-accounts - not implemented).
 221
 222
 223 alias/remove?alias_username=foo&alias_domain=bar.bz
 224 alias/remove?alias=foo@bar.bz
 225         Removes the alias given by alias_username and alias_domain.
 226
 227         Returns 'ok' with the removed alias adress as 'alias' on success
 228
 229         Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
 230         exists.
 231
 232         Returns 'invalid' with 'cause' = 'address' if the given alias is not a
 233         valid SIP adress.
 234
 235 BUGS:
 236 ---------------------
 237
 238 api/alias/list?destination=foo@bar.bz&e164=true
 239         should return an empty array, returns false
 240
 241 TODO list:
 242 ---------------------
 243
 244 Add a node to test a destination (pre-flight testing of user/add and alias/add)
 245
 246 Read list of kamailio domains (domains/list ?) RW?
 247 Default server-settings for domains (domains/server ? ) (registrar, proxy, ports...) RW.
 248 Permissions! (user/permissions?user=...)
 249
 250 authentication-mechanism :)
 251
 252 Change all GET to POST
 253
 254 Implement test-tool for POST-based communication ;)
 255
 256 Improve robustness of change_pw: fetch old password for rollback/testing.
 257
 258 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec