GNU Mailman

Merge lp:~abompard/mailman/bug-1400520 into lp:mailman

  1. bug-1400520
  2. Merge into 3.0
Proposed by Aurélien Bompard
Status: Merged
Approved by: Barry Warsaw
Approved revision: 7274
Merged at revision: 7274
Proposed branch: lp:~abompard/mailman/bug-1400520
Merge into: lp:mailman
Diff against target: 210 lines (+120/-10)
1 file modified
src/mailman/rest/docs/addresses.rst (+120/-10)
To merge this branch: bzr merge lp:~abompard/mailman/bug-1400520
Reviewer Review Type Date Requested Status
Barry Warsaw Approve
Review via email: mp+244137@code.launchpad.net

Description of the change

Documentation the new /addresses/<email>/user resource

To post a comment you must log in.
Revision history for this message
Barry Warsaw (barry) wrote :

Looks great, thanks!

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'src/mailman/rest/docs/addresses.rst'
2--- src/mailman/rest/docs/addresses.rst 2014-12-08 15:43:08 +0000
3+++ src/mailman/rest/docs/addresses.rst 2014-12-09 14:19:22 +0000
4@@ -144,6 +144,116 @@
5 self_link: http://localhost:9001/3.0/addresses/cris@example.com
6
7
8+Getting to the user
9+===================
10+
11+To link an address to a user, a POST request can be sent to the /user
12+namespace. If the user does not exist, it will be created and the request
13+status will be '201 Created'.
14+
15+ >>> user_manager.get_user('cris@example.com') is None
16+ True
17+ >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user',
18+ ... {'display_name': 'Cris User'})
19+ content-length: 0
20+ date: ...
21+ location: http://localhost:9001/3.0/users/1
22+ server: ...
23+ status: 201
24+ >>> transaction.commit()
25+
26+The user is now created and the address is linked to it:
27+
28+ >>> cris.user
29+ <User "Cris User" (1) at 0x...>
30+ >>> cris_user = user_manager.get_user('cris@example.com')
31+ >>> cris_user
32+ <User "Cris User" (1) at 0x...>
33+ >>> cris.user == cris_user
34+ True
35+ >>> [a.email for a in cris_user.addresses]
36+ [u'cris@example.com']
37+
38+A link to the user resource is now available in the address' REST
39+representation:
40+
41+ >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com')
42+ display_name: Cris Person
43+ email: cris@example.com
44+ http_etag: "..."
45+ original_email: cris@example.com
46+ registered_on: 2005-08-01T07:49:23
47+ self_link: http://localhost:9001/3.0/addresses/cris@example.com
48+ user: http://localhost:9001/3.0/users/1
49+ >>> transaction.commit()
50+
51+To prevent automatic user creation from taking place, add the 'auto_create'
52+parameter in the request and set it to a false-equivalent value like 0:
53+
54+ >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com/user',
55+ ... {'display_name': 'Anne User', 'auto_create': 0})
56+ Traceback (most recent call last):
57+ ...
58+ HTTPError: HTTP Error 403: 403 Forbidden
59+
60+A request to the /user namespace will return the linked user's representation:
61+
62+ >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user')
63+ created_on: 2005-08-01T07:49:23
64+ display_name: Cris User
65+ http_etag: "..."
66+ password: ...
67+ self_link: http://localhost:9001/3.0/users/1
68+ user_id: 1
69+
70+The address and the user can be unlinked by sending a DELETE request on the
71+/user namespace (the user itself is not deleted, only the link):
72+
73+ >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user',
74+ ... method='DELETE')
75+ content-length: 0
76+ date: ...
77+ server: ...
78+ status: 204
79+ >>> transaction.commit()
80+ >>> cris.user == None
81+ True
82+ >>> from uuid import UUID
83+ >>> user_manager.get_user_by_id(UUID(int=1)) is not None
84+ True
85+ >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user')
86+ Traceback (most recent call last):
87+ ...
88+ HTTPError: HTTP Error 404: 404 Not Found
89+
90+To link an address to a specific existing user, add this user's user_id in the
91+POST request:
92+
93+ >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user',
94+ ... {'user_id': 1})
95+ content-length: 0
96+ date: ...
97+ server: ...
98+ status: 200
99+ >>> transaction.commit()
100+ >>> cris.user
101+ <User "Cris User" (1) at 0x...>
102+
103+To link an address to a different user, you can either send a DELETE request
104+followed by a POST request, or you can send a PUT request.
105+
106+ >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user',
107+ ... {'display_name': 'Another Cris User'}, method="PUT")
108+ content-length: 0
109+ date: ...
110+ location: http://localhost:9001/3.0/users/2
111+ server: ...
112+ status: 201
113+ >>> transaction.commit()
114+ >>> cris.user
115+ <User "Another Cris User" (2) at 0x...>
116+
117+
118 User addresses
119 ==============
120
121@@ -161,7 +271,7 @@
122 original_email: dave@example.com
123 registered_on: 2005-08-01T07:49:23
124 self_link: http://localhost:9001/3.0/addresses/dave@example.com
125- user: http://localhost:9001/3.0/users/1
126+ user: http://localhost:9001/3.0/users/3
127 http_etag: "..."
128 start: 0
129 total_size: 1
130@@ -173,7 +283,7 @@
131 original_email: dave@example.com
132 registered_on: 2005-08-01T07:49:23
133 self_link: http://localhost:9001/3.0/addresses/dave@example.com
134- user: http://localhost:9001/3.0/users/1
135+ user: http://localhost:9001/3.0/users/3
136
137 A user can be associated with multiple email addresses. You can add new
138 addresses to an existing user.
139@@ -210,7 +320,7 @@
140 original_email: dave.person@example.org
141 registered_on: 2005-08-01T07:49:23
142 self_link: http://localhost:9001/3.0/addresses/dave.person@example.org
143- user: http://localhost:9001/3.0/users/1
144+ user: http://localhost:9001/3.0/users/3
145 entry 1:
146 display_name: Dave Person
147 email: dave@example.com
148@@ -218,7 +328,7 @@
149 original_email: dave@example.com
150 registered_on: 2005-08-01T07:49:23
151 self_link: http://localhost:9001/3.0/addresses/dave@example.com
152- user: http://localhost:9001/3.0/users/1
153+ user: http://localhost:9001/3.0/users/3
154 entry 2:
155 display_name: Davie P
156 email: dp@example.org
157@@ -226,7 +336,7 @@
158 original_email: dp@example.org
159 registered_on: 2005-08-01T07:49:23
160 self_link: http://localhost:9001/3.0/addresses/dp@example.org
161- user: http://localhost:9001/3.0/users/1
162+ user: http://localhost:9001/3.0/users/3
163 http_etag: "..."
164 start: 0
165 total_size: 3
166@@ -273,7 +383,7 @@
167 list_id: ant.example.com
168 role: member
169 self_link: http://localhost:9001/3.0/members/1
170- user: http://localhost:9001/3.0/users/2
171+ user: http://localhost:9001/3.0/users/4
172 entry 1:
173 address: http://localhost:9001/3.0/addresses/elle@example.com
174 delivery_mode: regular
175@@ -282,7 +392,7 @@
176 list_id: bee.example.com
177 role: member
178 self_link: http://localhost:9001/3.0/members/2
179- user: http://localhost:9001/3.0/users/2
180+ user: http://localhost:9001/3.0/users/4
181 http_etag: "..."
182 start: 0
183 total_size: 2
184@@ -312,7 +422,7 @@
185 list_id: ant.example.com
186 role: member
187 self_link: http://localhost:9001/3.0/members/1
188- user: http://localhost:9001/3.0/users/2
189+ user: http://localhost:9001/3.0/users/4
190 entry 1:
191 address: http://localhost:9001/3.0/addresses/elle@example.com
192 delivery_mode: regular
193@@ -321,7 +431,7 @@
194 list_id: bee.example.com
195 role: member
196 self_link: http://localhost:9001/3.0/members/2
197- user: http://localhost:9001/3.0/users/2
198+ user: http://localhost:9001/3.0/users/4
199 http_etag: "..."
200 start: 0
201 total_size: 2
202@@ -336,7 +446,7 @@
203 list_id: bee.example.com
204 role: member
205 self_link: http://localhost:9001/3.0/members/3
206- user: http://localhost:9001/3.0/users/2
207+ user: http://localhost:9001/3.0/users/4
208 http_etag: "..."
209 start: 0
210 total_size: 1