1 files changed, 107 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