diff options
| -rw-r--r-- | src/mailman/rest/docs/addresses.rst | 67 |
1 files changed, 35 insertions, 32 deletions
diff --git a/src/mailman/rest/docs/addresses.rst b/src/mailman/rest/docs/addresses.rst index f7a07a638..bab2a7210 100644 --- a/src/mailman/rest/docs/addresses.rst +++ b/src/mailman/rest/docs/addresses.rst @@ -144,38 +144,33 @@ Now Cris's address is unverified. self_link: http://localhost:9001/3.0/addresses/cris@example.com -Getting to the user -=================== +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'. +To link an address to a user, a POST request can be sent to the ``/user`` +sub-resource of the address. If the user does not exist, it will be created. - >>> user_manager.get_user('cris@example.com') is None - True >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user', - ... {'display_name': 'Cris User'}) + ... {'display_name': 'Cris X. Person'}) 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...> + <User "Cris X. Person" (1) at 0x...> >>> cris_user = user_manager.get_user('cris@example.com') >>> cris_user - <User "Cris User" (1) at 0x...> + <User "Cris X. Person" (1) at 0x...> >>> cris.user == cris_user True >>> [a.email for a in cris_user.addresses] [u'cris@example.com'] -A link to the user resource is now available in the address' REST -representation: +A link to the user resource is now available as a sub-resource. >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com') display_name: Cris Person @@ -185,10 +180,9 @@ representation: registered_on: 2005-08-01T07:49:23 self_link: http://localhost:9001/3.0/addresses/cris@example.com 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: +To prevent automatic user creation from taking place, add the `auto_create` +parameter to the POST request and set it to a false-equivalent value like 0: >>> dump_json('http://localhost:9001/3.0/addresses/anne@example.com/user', ... {'display_name': 'Anne User', 'auto_create': 0}) @@ -196,18 +190,19 @@ parameter in the request and set it to a false-equivalent value like 0: ... HTTPError: HTTP Error 403: 403 Forbidden -A request to the /user namespace will return the linked user's representation: +A request to the `/user` sub-resource will return the linked user's +representation: >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user') created_on: 2005-08-01T07:49:23 - display_name: Cris User + display_name: Cris X. Person 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): +`/user` resource. The user itself is not deleted, only the link. >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user', ... method='DELETE') @@ -215,19 +210,19 @@ The address and the user can be unlinked by sending a DELETE request on the date: ... server: ... status: 204 - >>> transaction.commit() + >>> transaction.abort() >>> cris.user == None True >>> from uuid import UUID - >>> user_manager.get_user_by_id(UUID(int=1)) is not None - True + >>> user_manager.get_user_by_id(UUID(int=1)) + <User "Cris X. Person" (1) at 0x...> >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/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: +You can link an existing user to an address by passing the user's ID in the +POST request. >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user', ... {'user_id': 1}) @@ -235,30 +230,38 @@ POST request: date: ... server: ... status: 200 - >>> transaction.commit() - >>> cris.user - <User "Cris User" (1) at 0x...> + >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user') + created_on: ... + display_name: Cris X. Person + http_etag: ... + password: ... + self_link: http://localhost:9001/3.0/users/1 + user_id: 1 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/cris@example.com/user', - ... {'display_name': 'Another Cris User'}, method="PUT") + ... {'display_name': 'Cris Q Person'}, 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...> + >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user') + created_on: ... + display_name: Cris Q Person + http_etag: ... + password: ... + self_link: http://localhost:9001/3.0/users/2 + user_id: 2 User addresses ============== Users control addresses. The canonical URLs for these user-controlled -addresses live in the /addresses namespace. +addresses live in the `/addresses` namespace. :: >>> dave = user_manager.create_user('dave@example.com', 'Dave Person') |