Aurélien Bompard has proposed merging lp:~abompard/mailman/bug-1400520 into
lp:mailman.
Requested reviews:
Mailman Coders (mailman-coders)
Related bugs:
Bug #1400520 in GNU Mailman: "/addresses/<email>/user REST resource needs
documentation"
https://bugs.launchpad.net/mailman/+bug/1400520
For more details, see:
https://code.launchpad.net/~abompard/mailman/bug-1400520/+merge/244137
Documentation the new /addresses/<email>/user resource
--
Your team Mailman Coders is requested to review the proposed merge of
lp:~abompard/mailman/bug-1400520 into lp:mailman.
=== modified file 'src/mailman/rest/docs/addresses.rst'
--- src/mailman/rest/docs/addresses.rst 2014-12-08 15:43:08 +0000
+++ src/mailman/rest/docs/addresses.rst 2014-12-09 14:12:52 +0000
@@ -144,6 +144,116 @@
self_link: http://localhost:9001/3.0/addresses/[email protected]
+Getting to the user
+===================
+
+To link an address to a user, a POST request can be sent to the /user
+namespace. If the user does not exist, it will be created and the request
+status will be '201 Created'.
+
+ >>> user_manager.get_user('[email protected]') is None
+ True
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]/user',
+ ... {'display_name': 'Cris User'})
+ content-length: 0
+ date: ...
+ location: http://localhost:9001/3.0/users/1
+ server: ...
+ status: 201
+ >>> transaction.commit()
+
+The user is now created and the address is linked to it:
+
+ >>> cris.user
+ <User "Cris User" (1) at 0x...>
+ >>> cris_user = user_manager.get_user('[email protected]')
+ >>> cris_user
+ <User "Cris User" (1) at 0x...>
+ >>> cris.user == cris_user
+ True
+ >>> [a.email for a in cris_user.addresses]
+ [u'[email protected]']
+
+A link to the user resource is now available in the address' REST
+representation:
+
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]')
+ display_name: Cris Person
+ email: [email protected]
+ http_etag: "..."
+ original_email: [email protected]
+ registered_on: 2005-08-01T07:49:23
+ self_link: http://localhost:9001/3.0/addresses/[email protected]
+ user: http://localhost:9001/3.0/users/1
+ >>> transaction.commit()
+
+To prevent automatic user creation from taking place, add the 'auto_create'
+parameter in the request and set it to a false-equivalent value like 0:
+
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]/user',
+ ... {'display_name': 'Anne User', 'auto_create': 0})
+ Traceback (most recent call last):
+ ...
+ HTTPError: HTTP Error 403: 403 Forbidden
+
+A request to the /user namespace will return the linked user's representation:
+
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]/user')
+ created_on: 2005-08-01T07:49:23
+ display_name: Cris User
+ http_etag: "..."
+ password: ...
+ self_link: http://localhost:9001/3.0/users/1
+ user_id: 1
+
+The address and the user can be unlinked by sending a DELETE request on the
+/user namespace (the user itself is not deleted, only the link):
+
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]/user',
+ ... method='DELETE')
+ content-length: 0
+ date: ...
+ server: ...
+ status: 204
+ >>> transaction.commit()
+ >>> cris.user == None
+ True
+ >>> from uuid import UUID
+ >>> user_manager.get_user_by_id(UUID(int=1)) is not None
+ True
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]/user')
+ Traceback (most recent call last):
+ ...
+ HTTPError: HTTP Error 404: 404 Not Found
+
+To link an address to a specific existing user, add this user's user_id in the
+POST request:
+
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]/user',
+ ... {'user_id': 1})
+ content-length: 0
+ date: ...
+ server: ...
+ status: 200
+ >>> transaction.commit()
+ >>> cris.user
+ <User "Cris User" (1) at 0x...>
+
+To link an address to a different user, you can either send a DELETE request
+followed by a POST request, or you can send a PUT request.
+
+ >>> dump_json('http://localhost:9001/3.0/addresses/[email protected]/user',
+ ... {'display_name': 'Another Cris User'}, method="PUT")
+ content-length: 0
+ date: ...
+ location: http://localhost:9001/3.0/users/2
+ server: ...
+ status: 201
+ >>> transaction.commit()
+ >>> cris.user
+ <User "Another Cris User" (2) at 0x...>
+
+
User addresses
==============
@@ -161,7 +271,7 @@
original_email: [email protected]
registered_on: 2005-08-01T07:49:23
self_link: http://localhost:9001/3.0/addresses/[email protected]
- user: http://localhost:9001/3.0/users/1
+ user: http://localhost:9001/3.0/users/3
http_etag: "..."
start: 0
total_size: 1
@@ -173,7 +283,7 @@
original_email: [email protected]
registered_on: 2005-08-01T07:49:23
self_link: http://localhost:9001/3.0/addresses/[email protected]
- user: http://localhost:9001/3.0/users/1
+ user: http://localhost:9001/3.0/users/3
A user can be associated with multiple email addresses. You can add new
addresses to an existing user.
@@ -210,7 +320,7 @@
original_email: [email protected]
registered_on: 2005-08-01T07:49:23
self_link: http://localhost:9001/3.0/addresses/[email protected]
- user: http://localhost:9001/3.0/users/1
+ user: http://localhost:9001/3.0/users/3
entry 1:
display_name: Dave Person
email: [email protected]
@@ -218,7 +328,7 @@
original_email: [email protected]
registered_on: 2005-08-01T07:49:23
self_link: http://localhost:9001/3.0/addresses/[email protected]
- user: http://localhost:9001/3.0/users/1
+ user: http://localhost:9001/3.0/users/3
entry 2:
display_name: Davie P
email: [email protected]
@@ -226,7 +336,7 @@
original_email: [email protected]
registered_on: 2005-08-01T07:49:23
self_link: http://localhost:9001/3.0/addresses/[email protected]
- user: http://localhost:9001/3.0/users/1
+ user: http://localhost:9001/3.0/users/3
http_etag: "..."
start: 0
total_size: 3
@@ -273,7 +383,7 @@
list_id: ant.example.com
role: member
self_link: http://localhost:9001/3.0/members/1
- user: http://localhost:9001/3.0/users/2
+ user: http://localhost:9001/3.0/users/4
entry 1:
address: http://localhost:9001/3.0/addresses/[email protected]
delivery_mode: regular
@@ -282,7 +392,7 @@
list_id: bee.example.com
role: member
self_link: http://localhost:9001/3.0/members/2
- user: http://localhost:9001/3.0/users/2
+ user: http://localhost:9001/3.0/users/4
http_etag: "..."
start: 0
total_size: 2
@@ -312,7 +422,7 @@
list_id: ant.example.com
role: member
self_link: http://localhost:9001/3.0/members/1
- user: http://localhost:9001/3.0/users/2
+ user: http://localhost:9001/3.0/users/4
entry 1:
address: http://localhost:9001/3.0/addresses/[email protected]
delivery_mode: regular
@@ -321,7 +431,7 @@
list_id: bee.example.com
role: member
self_link: http://localhost:9001/3.0/members/2
- user: http://localhost:9001/3.0/users/2
+ user: http://localhost:9001/3.0/users/4
http_etag: "..."
start: 0
total_size: 2
@@ -336,7 +446,7 @@
list_id: bee.example.com
role: member
self_link: http://localhost:9001/3.0/members/3
- user: http://localhost:9001/3.0/users/2
+ user: http://localhost:9001/3.0/users/4
http_etag: "..."
start: 0
total_size: 1
_______________________________________________
Mailman-coders mailing list
[email protected]
https://mail.python.org/mailman/listinfo/mailman-coders
