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
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
=======
Domains
=======
`Domains`_ are how Mailman interacts with email host names and web host names.
::
# The test framework starts out with an example domain, so let's delete
# that first.
>>> from mailman.interfaces.domain import IDomainManager
>>> from zope.component import getUtility
>>> domain_manager = getUtility(IDomainManager)
>>> domain_manager.remove('example.com')
<Domain example.com...>
>>> transaction.commit()
The REST API can be queried for the set of known domains, of which there are
initially none.
>>> dump_json('http://localhost:9001/3.0/domains')
http_etag: "..."
start: 0
total_size: 0
Once a domain is added, it is accessible through the API.
::
>>> domain_manager.add(
... 'example.com', 'An example domain', 'http://lists.example.com')
<Domain example.com, An example domain, base_url: http://lists.example.com>
>>> transaction.commit()
>>> dump_json('http://localhost:9001/3.0/domains')
entry 0:
base_url: http://lists.example.com
description: An example domain
http_etag: "..."
mail_host: example.com
self_link: http://localhost:9001/3.0/domains/example.com
url_host: lists.example.com
http_etag: "..."
start: 0
total_size: 1
At the top level, all domains are returned as separate entries.
::
>>> domain_manager.add(
... 'example.org',
... base_url='http://mail.example.org')
<Domain example.org, base_url: http://mail.example.org>
>>> domain_manager.add(
... 'lists.example.net',
... 'Porkmasters',
... 'http://example.net')
<Domain lists.example.net, Porkmasters, base_url: http://example.net>
>>> transaction.commit()
>>> dump_json('http://localhost:9001/3.0/domains')
entry 0:
base_url: http://lists.example.com
description: An example domain
http_etag: "..."
mail_host: example.com
self_link: http://localhost:9001/3.0/domains/example.com
url_host: lists.example.com
entry 1:
base_url: http://mail.example.org
description: None
http_etag: "..."
mail_host: example.org
self_link: http://localhost:9001/3.0/domains/example.org
url_host: mail.example.org
entry 2:
base_url: http://example.net
description: Porkmasters
http_etag: "..."
mail_host: lists.example.net
self_link: http://localhost:9001/3.0/domains/lists.example.net
url_host: example.net
http_etag: "..."
start: 0
total_size: 3
Individual domains
==================
The information for a single domain is available by following one of the
``self_links`` from the above collection.
>>> dump_json('http://localhost:9001/3.0/domains/lists.example.net')
base_url: http://example.net
description: Porkmasters
http_etag: "..."
mail_host: lists.example.net
self_link: http://localhost:9001/3.0/domains/lists.example.net
url_host: example.net
You can also list all the mailing lists for a given domain. At first, the
example.com domain does not contain any mailing lists.
::
>>> dump_json('http://localhost:9001/3.0/domains/example.com/lists')
http_etag: "..."
start: 0
total_size: 0
>>> dump_json('http://localhost:9001/3.0/lists', {
... 'fqdn_listname': 'test-domains@example.com',
... })
content-length: 0
content-type: application/json; charset=UTF-8
date: ...
location: http://localhost:9001/3.0/lists/test-domains.example.com
...
>>> dump_json('http://localhost:9001/3.0/domains/example.com/lists')
entry 0:
display_name: Test-domains
fqdn_listname: test-domains@example.com
http_etag: "..."
...
member_count: 0
self_link: http://localhost:9001/3.0/lists/test-domains.example.com
volume: 1
http_etag: "..."
start: 0
total_size: 1
Other domains continue to contain no mailing lists.
>>> dump_json('http://localhost:9001/3.0/domains/lists.example.net/lists')
http_etag: "..."
start: 0
total_size: 0
Creating new domains
====================
New domains can be created by posting to the ``domains`` url.
>>> dump_json('http://localhost:9001/3.0/domains', {
... 'mail_host': 'lists.example.com',
... })
content-length: 0
content-type: application/json; charset=UTF-8
date: ...
location: http://localhost:9001/3.0/domains/lists.example.com
...
Now the web service knows about our new domain.
>>> dump_json('http://localhost:9001/3.0/domains/lists.example.com')
base_url: http://lists.example.com
description: None
http_etag: "..."
mail_host: lists.example.com
self_link: http://localhost:9001/3.0/domains/lists.example.com
url_host: lists.example.com
And the new domain is in our database.
::
>>> domain_manager['lists.example.com']
<Domain lists.example.com, base_url: http://lists.example.com>
# Unlock the database.
>>> transaction.abort()
You can also create a new domain with a description, a base url, and a contact
address.
::
>>> dump_json('http://localhost:9001/3.0/domains', {
... 'mail_host': 'my.example.com',
... 'description': 'My new domain',
... 'base_url': 'http://allmy.example.com'
... })
content-length: 0
content-type: application/json; charset=UTF-8
date: ...
location: http://localhost:9001/3.0/domains/my.example.com
...
>>> dump_json('http://localhost:9001/3.0/domains/my.example.com')
base_url: http://allmy.example.com
description: My new domain
http_etag: "..."
mail_host: my.example.com
self_link: http://localhost:9001/3.0/domains/my.example.com
url_host: allmy.example.com
>>> domain_manager['my.example.com']
<Domain my.example.com, My new domain, base_url: http://allmy.example.com>
# Unlock the database.
>>> transaction.abort()
Deleting domains
================
Domains can also be deleted via the API.
>>> dump_json('http://localhost:9001/3.0/domains/lists.example.com',
... method='DELETE')
content-length: 0
date: ...
server: ...
status: 204
Domain owners
=============
Domains can have owners. By posting some addresses to the owners resource,
you can add some domain owners. Currently our domain has no owners:
>>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners')
http_etag: ...
start: 0
total_size: 0
Anne and Bart volunteer to be a domain owners.
::
>>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners', (
... ('owner', 'anne@example.com'), ('owner', 'bart@example.com')
... ))
content-length: 0
date: ...
server: ...
status: 204
>>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners')
entry 0:
created_on: 2005-08-01T07:49:23
http_etag: ...
is_server_owner: False
self_link: http://localhost:9001/3.0/users/1
user_id: 1
entry 1:
created_on: 2005-08-01T07:49:23
http_etag: ...
is_server_owner: False
self_link: http://localhost:9001/3.0/users/2
user_id: 2
http_etag: ...
start: 0
total_size: 2
We can delete all the domain owners.
>>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners',
... method='DELETE')
content-length: 0
date: ...
server: ...
status: 204
Now there are no owners.
>>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners')
http_etag: ...
start: 0
total_size: 0
New domains can be created with owners.
>>> dump_json('http://localhost:9001/3.0/domains', (
... ('mail_host', 'your.example.com'),
... ('owner', 'anne@example.com'),
... ('owner', 'bart@example.com'),
... ))
content-length: 0
content-type: application/json; charset=UTF-8
date: ...
location: http://localhost:9001/3.0/domains/your.example.com
server: ...
status: 201
The new domain has the expected owners.
>>> dump_json('http://localhost:9001/3.0/domains/your.example.com/owners')
entry 0:
created_on: 2005-08-01T07:49:23
http_etag: ...
is_server_owner: False
self_link: http://localhost:9001/3.0/users/1
user_id: 1
entry 1:
created_on: 2005-08-01T07:49:23
http_etag: ...
is_server_owner: False
self_link: http://localhost:9001/3.0/users/2
user_id: 2
http_etag: ...
start: 0
total_size: 2
.. _Domains: ../../model/docs/domains.html
|
