git.defcon.no Git - hermes/blob - 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
  64         Not implemented! Will only be implemented for Local users.
  65         Remote users will have to be removed, and re-added.
  66
  67
  68 user/remove?username=foo&domain=bar
  69 user/remove?user=foo@bar.bz
  70         Removes user account from Kamailio, if present, and removes user from
  71         provisioning.  Will fail if user has associated hardphones, remove
  72         phones before removing user.
  73
  74         Returns 'ok' on success.
  75
  76 user/gen_pw
  77         Test-node, generates a random password on the same form as that used by
  78         user/add_local. May be used with the to-be-implemented change_pw node.
  79
  80 phone/get?mac=f00ba2ba5c00
  81 phone/get?user=foo@bar.bz
  82 phone/get?username=foo&domain=bar.bz
  83         Returns a list of associated elements. If MAC address is given as
  84         parameter, a list of associated user@domain addresses is retruned. If
  85         user@domain is given as parameter, a list of associated mac addresses
  86         is returned.
  87
  88 phone/list?search=f00ba2
  89         Returns the list of registered MAC addresses. If the (optional) search
  90         parameter is included, the list is the result of a globbing search,
  91         a subset matching on the MAC addresses.
  92
  93 phone/add?mac=f00ba2ba5c00&username=foo&domain=bar.bz
  94 phone/add?mac=f00ba2ba5c00&user=foo@bar.bz
  95         Adds a phone-to-user association to Provisioning. The user may be
  96         provided as 'username' and 'domain' in separate parameters, or as
  97         'user' in sip-address form. The MAC address must be valid, in plain-hex
  98         or colon-separated form, and the user must match a valid user
  99         registration.
 100
 101         Returns the mac+user combinations on success.
 102
 103 phone/remove?mac=f00ba2ba5c00&username=foo&domain=bar.bz
 104 phone/remove?mac=f00ba2ba5c00&user=foo@bar.bz
 105         Deletes a phone-to-user association. Required parameters and formats
 106         are identical to the phone/add node.
 107         Returns 'ok' on success.
 108
 109
 110 numbers/list
 111 numbers/list?search=1234
 112 numbers/list?random=true
 113   optional: limit=n
 114         Gives a list of entries in the phone number pool.
 115         With no parameters, the entire (ordered) list of available numbers is
 116         returned.  With 'search', the result of a pre-post globbing search is
 117         returned With 'random', a list of entries is returned unordered (random
 118         order) For all nodes, 'limit' may be a numeric limit of desired
 119         results.
 120
 121 numbers/add_range?start=%2B471234&end=%2B47123456
 122         The start and end must have identical lead-in, and start must be less
 123         than end.  Both numbers must be given in E164 format, remember to
 124         urlencode the plus (+ -> %2B). The numeric component of both will be
 125         extracted, and all numbers in the range will be iteratively added to
 126         the pool, including the ending number.
 127         Returns 'ok' on success.
 128
 129 numbers/add?number=%2B4761123456
 130         Adds the given number to the pool, after verifying that the number is
 131         in valid E164 format, and that the number does not already exist in the
 132         pool.
 133
 134         Returns 'response' 'ok' and "Added <number>" in 'detail' on success.
 135
 136 numbers/remove?number=%2B4761123456
 137         Removes/pulls a number from the pool.
 138         The number must be a valid e164 number, and must be present in the
 139         pool.
 140
 141         Returns 'response' as 'ok' with 'number' set to the number that was
 142         pulled from the pool.
 143
 144 numbers/inpool?number=%2B4761123456
 145         Tests if the given E164 number is in the pool.
 146         Returns 'response' = 'ok' with 'number' = '<number>' If the number is
 147         in the pool
 148
 149         Returns response = 'failed' with 'cause' = 'nonexistant' if not.
 150
 151 alias/list
 152 alias/list?destination=foo@bar.bz
 153 alias/list?destination=foo@bar.bz&e164=true
 154 alias/list?alias=foo@bar.bz
 155         Currently not implemented
 156
 157 alias/add?alias_username=foo&alias_domain=bar.bz&destination=bar@qux.zx
 158 alias/add?alias=foo@bar.bz&destination=bar@qux.zx
 159         Add an alias specified by alias_username and alias_domain that
 160         points to the destination SIP-adress.
 161
 162         On success, 'ok' is returned, with 'alias' and 'destination' set to the
 163         resulting alias and destination adresses.
 164
 165         Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
 166         resulting alias-adress or destination are invalid SIP-adresses.
 167
 168         Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain is
 169         not a Kamailio domain.
 170
 171         Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
 172         and the user already has an E164 alias registered.
 173
 174         Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
 175         domain is requested, but the local subscriber does not exist.
 176
 177         Returns 'failed' with 'cause' = 'exists' for aliases that already
 178         exists, (and aliases that overlaps SIP-accounts - not implemented).
 179
 180
 181 alias/remove?alias_username=foo&alias_domain=bar.bz
 182 alias/remove?alias=foo@bar.bz
 183         Removes the alias given by alias_username and alias_domain.
 184
 185         Returns 'ok' with the removed alias adress as 'alias' on success
 186
 187         Returns 'failed' with 'cause' = 'nonexistant' it the alias does not
 188         exists.
 189
 190         Returns 'invalid' with 'cause' = 'address' if the given alias is not a
 191         valid SIP adress.
 192
 193 TODO list:
 194 ---------------------
 195 Planned, but not implemented nodes/functions:
 196         user/update?username=foo&domain=bar
 197         alias/list
 198         alias/user?destination=foo@bar.bz
 199
 200 authentication-mechanism :)
 201
 202 Add collision prevention for users, make sure that no user can be added when the user
 203 address would overlap/collide with a valid alias-address
 204
 205 Change all GET to POST
 206
 207 Implement test-tool for POST-based communication ;)
 208
 209 Improve robustness of change_pw: fetch old password for rollback/testing.
 210
 211 Check for locations where sql_dbexec_rows is more appropriate/correct than sql_dbexec