=====
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