diff options
Diffstat (limited to 'src/mailman/rest')
| -rw-r--r-- | src/mailman/rest/docs/users.txt | 107 | ||||
| -rw-r--r-- | src/mailman/rest/root.py | 10 | ||||
| -rw-r--r-- | src/mailman/rest/users.py | 119 |
3 files changed, 236 insertions, 0 deletions
diff --git a/src/mailman/rest/docs/users.txt b/src/mailman/rest/docs/users.txt new file mode 100644 index 000000000..d6ac3e4c2 --- /dev/null +++ b/src/mailman/rest/docs/users.txt @@ -0,0 +1,107 @@ +===== +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. +:: + + >>> user_manager.get_user('bart@example.com') + <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: None + 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: None + real_name: Bart Person + user_id: 2 + + +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 diff --git a/src/mailman/rest/root.py b/src/mailman/rest/root.py index 9d8c92428..3287a6be2 100644 --- a/src/mailman/rest/root.py +++ b/src/mailman/rest/root.py @@ -34,6 +34,7 @@ from mailman.rest.domains import ADomain, AllDomains from mailman.rest.helpers import etag, path_to from mailman.rest.lists import AList, AllLists from mailman.rest.members import AllMembers +from mailman.rest.users import AUser, AllUsers @@ -108,3 +109,12 @@ class TopLevel(resource.Resource): if len(segments) == 0: return AllMembers() return http.bad_request() + + @resource.child() + def users(self, request, segments): + """/<api>/users""" + if len(segments) == 0: + return AllUsers() + else: + user_id = segments.pop(0) + return AUser(user_id), segments diff --git a/src/mailman/rest/users.py b/src/mailman/rest/users.py new file mode 100644 index 000000000..9a00cecd2 --- /dev/null +++ b/src/mailman/rest/users.py @@ -0,0 +1,119 @@ +# Copyright (C) 2011 by the Free Software Foundation, Inc. +# +# This file is part of GNU Mailman. +# +# GNU Mailman is free software: you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free +# Software Foundation, either version 3 of the License, or (at your option) +# any later version. +# +# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +# more details. +# +# You should have received a copy of the GNU General Public License along with +# GNU Mailman. If not, see <http://www.gnu.org/licenses/>. + +"""REST for users.""" + +from __future__ import absolute_import, unicode_literals + +__metaclass__ = type +__all__ = [ + 'AUser', + 'AllUsers', + ] + + +from restish import http, resource +from zope.component import getUtility + +from mailman.interfaces.address import ExistingAddressError +from mailman.interfaces.usermanager import IUserManager +from mailman.rest.helpers import CollectionMixin, etag, path_to +from mailman.rest.validator import Validator + + + +class _UserBase(resource.Resource, CollectionMixin): + """Shared base class for user representations.""" + + def _resource_as_dict(self, user): + """See `CollectionMixin`.""" + # The canonical URL for a user is their preferred email address, + # although we can always look up a user based on any registered and + # validated email address associated with their account. + return dict( + real_name=user.real_name, + password=user.password, + user_id=user.user_id, + created_on=user.created_on, + ) + + def _get_collection(self, request): + """See `CollectionMixin`.""" + return list(getUtility(IUserManager).users) + + + +class AllUsers(_UserBase): + """The users.""" + + @resource.GET() + def collection(self, request): + """/users""" + resource = self._make_collection(request) + return http.ok([], etag(resource)) + + @resource.POST() + def create(self, request): + """Create a new user.""" + try: + validator = Validator(email=unicode, + real_name=unicode, + password=unicode, + _optional=('real_name', 'password')) + arguments = validator(request) + except ValueError as error: + return http.bad_request([], str(error)) + # We can't pass the 'password' argument to the user creation method, + # so strip that out (if it exists), then create the user, adding the + # password after the fact if successful. + password = arguments.pop('password', None) + try: + user = getUtility(IUserManager).create_user(**arguments) + except ExistingAddressError as error: + return http.bad_request([], b'Address already exists {0}'.format( + error.email)) + # XXX ignore password for now. + location = path_to('users/{0}'.format(user.user_id)) + return http.created(location, [], None) + + + +class AUser(_UserBase): + """A user.""" + + def __init__(self, user_identifier): + """Get a user by various type of identifiers. + + :param user_identifier: The identifier used to retrieve the user. The + identifier may either be an integer user-id, or an email address + controlled by the user. The type of identifier is auto-detected + by looking for an `@` symbol, in which case it's taken as an email + address, otherwise it's assumed to be an integer. + :type user_identifier: str + """ + user_manager = getUtility(IUserManager) + if '@' in user_identifier: + self._user = user_manager.get_user(user_identifier) + else: + self._user = user_manager.get_user_by_id(user_identifier) + + @resource.GET() + def user(self, request): + """Return a single user end-point.""" + if self._user is None: + return http.not_found() + return http.ok([], self._resource_as_json(self._user)) |