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
  16         Return User information, not including hardphone association.
  17         Possible extension: allow user/get?address=foo@bar
  18
  19 user/list
  20 user/list?search=foo@bar
  21         Return a list of users in user@domain format.
  22         If the search parameter is included, a globbing search is performed,
  23         and only matches are listed.
  24
  25 user/add_local?username=foo&domain=bar&displayname=baz&email=qux@zef.tld
  26         Adds a user account to both Kamailio and provisioning,
  27         if the username@domain is nonexistant, and the domain is local (handled by Kamailio).
  28         The password for the user is auto-generated.
  29         Returns a full user object, the same form as user/get
  30
  31 user/add_remote?username=foo&domain=bar&password=S3cr3t&displayname=baz&registrar=sip.example.com
  32   optionals: &r_port=5060&proxy=sipproxy.example.com&p_port=5060&authid=realfoo&dialplan=(.*)&linetext=lalala
  33         Adds a provisioning user for a remote SIP account. This allows locally provisioned hardphones
  34         to be associated with non-local SIP accounts.
  35         Returns a full user object, the same form as user/get
  36
  37 user/remove?username=foo&domain=bar
  38         Removes user account from Kamailio, if present, and removes user from provisioning.
  39         Will fail if user has associated hardphones, remove phones before removing user.
  40         Returns 'ok' on success.
  41
  42 user/gen_pw
  43         Test-node, generates a random password on the same form as that used
  44         by user/add_local. May be used with the to-be-implemented change_pw node.
  45
  46 user/change_pw?username=foo&domain=bar&password=baz
  47         Not implemented!
  48
  49 user/update?username=foo&domain=bar
  50   optionals: &displayname=baz&dialplan=(.*)&linetext=lalala
  51         Not implemented! Will only be implemented for Local users.
  52         Remote users will have to be removed, and re-added.
  53
  54 phone/get?mac=f00ba2ba5c00
  55 phone/get?user=foo@bar.baz
  56         Returns a list of associated elements. If MAC address is given as parameter,
  57         a list of associated user@domain addresses is retruned. If user@domain is
  58         given as parameter, a list of associated mac addresses is returned.
  59
  60 phone/list?search=f00ba2
  61         Returns the list of registered MAC addresses. If the (optional) search
  62         parameter is included, the list is the result of a globbing search,
  63         a subset matching on the MAC addresses.
  64
  65 phone/add?mac=f00ba2ba5c00&username=foo&domain=bar.bz
  66 phone/add?mac=f00ba2ba5c00&user=foo@bar.bz
  67         Adds a phone-to-user association to Provisioning. The user may
  68         be provided as 'username' and 'domain' in separate parameters,
  69         or as 'user' in sip-address form. The MAC address must be valid,
  70         in plain-hex or colon-separated form, and the user must
  71         match a valid user registration.
  72         Returns the mac+user combinations on success.
  73
  74 phone/remove?mac=f00ba2ba5c00&username=foo&domain=bar.bz
  75 phone/remove?mac=f00ba2ba5c00&user=foo@bar.bz
  76         Deletes a phone-to-user association. Required parameters
  77         and formats are identical to the phone/add node.
  78         Returns 'ok' on success.
  79
  80
  81 numbers/list
  82 numbers/list?search=1234
  83 numbers/list?random=true
  84   optional: limit=n
  85         Gives a list of entries in the phone number pool.
  86         With no parameters, the entire (ordered) list of available numbers is returned.
  87         With 'search', the result of a pre-post globbing search is returned
  88         With 'random', a list of entries is returned unordered (random order)
  89         For all nodes, 'limit' may be a numeric limit of desired results.
  90
  91 numbers/add_range?start=%2B471234&end=%2B47123456
  92         The start and end must have identical lead-in, and start must be less than end.
  93         Both numbers must be given in E164 format, remember to urlencode the plus (+ -> %2B)
  94         The numeric component of both will be extracted, and all numbers in the range
  95         will be iteratively added to the pool, including the ending number.
  96         Returns 'ok' on success.
  97
  98 numbers/add?number=%2B4761123456
  99         Adds the given number to the pool, after verifying that the number is in
 100         valid E164 format, and that the number does not already exist in the pool.
 101         Returns 'response' 'ok' and "Added <number>" in 'detail' on success.
 102
 103 numbers/remove?number=%2B4761123456
 104         Removes/pulls a number from the pool.
 105         The number must be a valid e164 number, and must be present in the pool.
 106         Returns 'response' as 'ok' with 'number' set to the number that was pulled from the pool.
 107
 108 numbers/inpool?number=%2B4761123456
 109         A debug-node, may disappear at any time ^_^
 110         Tests if the given E164 number is in the pool.
 111         Returns 'response' = 'ok' with 'number' = '<number>' If the number is in the pool
 112         Returns response = 'failed' with 'cause' = 'nonexistant' if not.
 113
 114
 115 alias/list
 116         Currently not implemented.
 117
 118 alias/user?destination=foo@bar.bz
 119 alias/user?destination=foo@bar.bz&e164=true
 120         Currently not implemented
 121
 122 alias/add?alias_username=foo&alias_domain=bar.bz&destination=bar@qux.zx
 123         Add an alias specified by alias_username and alias_domain that
 124         points to the destination SIP-adress.
 125
 126         On success, 'ok' is returned, with 'alias' and 'destination' set
 127         to the resulting alias and destination adresses.
 128
 129         Returns 'invalid' with 'cause' = 'destination' or 'alias' if the
 130         resulting alias-adress or destination are invalid SIP-adresses.
 131         Returns 'failed' with 'cause' = 'nxdomain' if the given alias domain
 132         is not a Kamailio domain.
 133         Returns 'failed' with 'cause' = 'exists' if the alias is an E164 number
 134         and the user already has an E164 alias registered.
 135         Returns 'failed' with 'cause' = 'nonexistant' when an alias for a local
 136         domain is requested, but the local subscriber does not exist.
 137         Returns 'failed' with 'cause' = 'exists' for aliases that already exists,
 138         (and aliases that overlaps SIP-accounts - not implemented).
 139
 140
 141 alias/remove?alias_username=foo&alias_domain=bar.bz
 142         Removes the alias given by alias_username and alias_domain.
 143
 144         Returns 'ok' with the removed alias adress as 'alias' on success
 145         Returns 'failed' with 'cause' = 'nonexistant' it the alias does not exists.
 146         Returns 'invalid' with 'cause' = 'address' if the given alias is not a valid SIP adress.
 147
 148 TODO list:
 149 ---------------------
 150 Planned, but not implemented nodes/functions:
 151         user/change_pw?username=foo&domain=bar&password=baz
 152         user/update?username=foo&domain=bar
 153         alias/list
 154         alias/user?destination=foo@bar.bz
 155
 156 Parameter updates:
 157         Update nodes where username=foo&domain=bar.bz is used, to also support user=foo@bar.bz
 158                 user/get
 159                 user/add_local
 160                 user/add_remote
 161                 user/remove
 162                 user/change_pw
 163                 user/update
 164                 phone/get (reverse, needs username & domain param)
 165                 alias/add
 166                 alias/remove
 167
 168 authentication-mechanism :)