1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
=====
Users
=====
The REST API can be used to add and remove users, add and remove user
addresses, and change their preferred address, passord, or name. Users are
different than members; the latter represents an email address subscribed to a
specific mailing list. Users are just people that Mailman knows about.
There are no users yet.
>>> dump_json('http://localhost:9001/3.0/users')
http_etag: "..."
start: 0
total_size: 0
When there are users in the database, they can be retrieved as a collection.
::
>>> from zope.component import getUtility
>>> from mailman.interfaces.usermanager import IUserManager
>>> user_manager = getUtility(IUserManager)
>>> anne = user_manager.create_user('anne@example.com', 'Anne Person')
>>> transaction.commit()
>>> dump_json('http://localhost:9001/3.0/users')
entry 0:
created_on: 2005-08-01T07:49:23
http_etag: "..."
password: None
real_name: Anne Person
user_id: 1
http_etag: "..."
start: 0
total_size: 1
The user ids match.
>>> json = call_http('http://localhost:9001/3.0/users')
>>> json['entries'][0]['user_id'] == anne.user_id
True
Creating users via the API
==========================
New users can be created through the REST API. To do so requires the initial
email address for the user, and optionally the user's full name and password.
::
>>> transaction.abort()
>>> dump_json('http://localhost:9001/3.0/users', {
... 'email': 'bart@example.com',
... 'real_name': 'Bart Person',
... 'password': 'bbb',
... })
content-length: 0
date: ...
location: http://localhost:9001/3.0/users/2
server: ...
status: 201
The user exists in the database.
::
>>> bart = user_manager.get_user('bart@example.com')
>>> bart
<User "Bart Person" (2) at ...>
It is also available via the location given in the response.
>>> dump_json('http://localhost:9001/3.0/users/2')
created_on: 2005-08-01T07:49:23
http_etag: "..."
password: {CLEARTEXT}bbb
real_name: Bart Person
user_id: 2
Because email addresses just have an ``@`` sign in then, there's no confusing
them with user ids. Thus, a user can be retrieved via its email address.
>>> dump_json('http://localhost:9001/3.0/users/bart@example.com')
created_on: 2005-08-01T07:49:23
http_etag: "..."
password: {CLEARTEXT}bbb
real_name: Bart Person
user_id: 2
Users can be created without a password. A *user friendly* password will be
assigned to them automatically, but this password will be encrypted and
therefore cannot be retrieved. It can be reset though.
::
>>> transaction.abort()
>>> dump_json('http://localhost:9001/3.0/users', {
... 'email': 'cris@example.com',
... 'real_name': 'Cris Person',
... })
content-length: 0
date: ...
location: http://localhost:9001/3.0/users/3
server: ...
status: 201
>>> dump_json('http://localhost:9001/3.0/users/3')
created_on: 2005-08-01T07:49:23
http_etag: "..."
password: {CLEARTEXT}...
real_name: Cris Person
user_id: 3
Missing users
=============
It is of course an error to attempt to access a non-existent user, either by
user id...
::
>>> dump_json('http://localhost:9001/3.0/users/99')
Traceback (most recent call last):
...
HTTPError: HTTP Error 404: 404 Not Found
...or by email address.
::
>>> dump_json('http://localhost:9001/3.0/users/zed@example.org')
Traceback (most recent call last):
...
HTTPError: HTTP Error 404: 404 Not Found
User addresses
==============
Bart may have any number of email addresses associated with their user
account. We can find out all of these through the API. The addresses are
sorted in lexical order by original (i.e. case-preserved) email address.
::
>>> bart.register('bperson@example.com')
<Address: bperson@example.com [not verified] at ...>
>>> bart.register('bart.person@example.com')
<Address: bart.person@example.com [not verified] at ...>
>>> bart.register('Bart.Q.Person@example.com')
<Address: Bart.Q.Person@example.com [not verified]
key: bart.q.person@example.com at ...>
>>> transaction.commit()
>>> dump_json('http://localhost:9001/3.0/users/2/addresses')
entry 0:
email: bart.q.person@example.com
http_etag: "..."
original_email: Bart.Q.Person@example.com
real_name:
registered_on: None
verified_on: None
entry 1:
email: bart.person@example.com
http_etag: "..."
original_email: bart.person@example.com
real_name:
registered_on: None
verified_on: None
entry 2:
email: bart@example.com
http_etag: "..."
original_email: bart@example.com
real_name: Bart Person
registered_on: None
verified_on: None
entry 3:
email: bperson@example.com
http_etag: "..."
original_email: bperson@example.com
real_name:
registered_on: None
verified_on: None
http_etag: "..."
start: 0
total_size: 4
In fact, any of these addresses can be used to look up Bart's user record.
::
>>> dump_json('http://localhost:9001/3.0/users/bart@example.com')
created_on: 2005-08-01T07:49:23
http_etag: "..."
password: {CLEARTEXT}bbb
real_name: Bart Person
user_id: 2
>>> dump_json('http://localhost:9001/3.0/users/bart.person@example.com')
created_on: 2005-08-01T07:49:23
http_etag: "..."
password: {CLEARTEXT}bbb
real_name: Bart Person
user_id: 2
>>> dump_json('http://localhost:9001/3.0/users/bperson@example.com')
created_on: 2005-08-01T07:49:23
http_etag: "..."
password: {CLEARTEXT}bbb
real_name: Bart Person
user_id: 2
|
