]> git.defcon.no Git - hermes/blob - api-nodes.txt
Hermes is a framework for managing SIP-accounts, aliases and automatic phone-provisio...
[hermes] / 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 :)