1 files changed, 129 insertions, 0 deletions

diff --git a/src/mailman/rest/docs/lists.rst b/src/mailman/rest/docs/lists.rst
new file mode 100644
index 000000000..fd96507c3
--- /dev/null
+++ b/src/mailman/rest/docs/lists.rst
@@ -0,0 +1,129 @@
+=============
+Mailing lists
+=============
+
+The REST API can be queried for the set of known mailing lists.  There is a
+top level collection that can return all the mailing lists.  There aren't any
+yet though.
+
+    >>> dump_json('http://localhost:9001/3.0/lists')
+    http_etag: "..."
+    start: 0
+    total_size: 0
+
+Create a mailing list in a domain and it's accessible via the API.
+::
+
+    >>> create_list('test-one@example.com')
+    <mailing list "test-one@example.com" at ...>
+    >>> transaction.commit()
+
+    >>> dump_json('http://localhost:9001/3.0/lists')
+    entry 0:
+        fqdn_listname: test-one@example.com
+        http_etag: "..."
+        list_name: test-one
+        mail_host: example.com
+        real_name: Test-one
+        self_link: http://localhost:9001/3.0/lists/test-one@example.com
+    http_etag: "..."
+    start: 0
+    total_size: 1
+
+
+Creating lists via the API
+==========================
+
+New mailing lists can also be created through the API, by posting to the
+``lists`` URL.
+
+    >>> dump_json('http://localhost:9001/3.0/lists', {
+    ...           'fqdn_listname': 'test-two@example.com',
+    ...           })
+    content-length: 0
+    date: ...
+    location: http://localhost:9001/3.0/lists/test-two@example.com
+    ...
+
+The mailing list exists in the database.
+::
+
+    >>> from mailman.interfaces.listmanager import IListManager
+    >>> from zope.component import getUtility
+    >>> list_manager = getUtility(IListManager)
+
+    >>> list_manager.get('test-two@example.com')
+    <mailing list "test-two@example.com" at ...>
+
+    # The above starts a Storm transaction, which will lock the database
+    # unless we abort it.
+    >>> transaction.abort()
+
+It is also available via the location given in the response.
+
+    >>> dump_json('http://localhost:9001/3.0/lists/test-two@example.com')
+    fqdn_listname: test-two@example.com
+    http_etag: "..."
+    list_name: test-two
+    mail_host: example.com
+    real_name: Test-two
+    self_link: http://localhost:9001/3.0/lists/test-two@example.com
+
+However, you are not allowed to create a mailing list in a domain that does
+not exist.
+
+    >>> dump_json('http://localhost:9001/3.0/lists', {
+    ...           'fqdn_listname': 'test-three@example.org',
+    ...           })
+    Traceback (most recent call last):
+    ...
+    HTTPError: HTTP Error 400: Domain does not exist example.org
+
+Nor can you create a mailing list that already exists.
+
+    >>> dump_json('http://localhost:9001/3.0/lists', {
+    ...           'fqdn_listname': 'test-one@example.com',
+    ...           })
+    Traceback (most recent call last):
+    ...
+    HTTPError: HTTP Error 400: Mailing list exists
+
+
+Deleting lists via the API
+==========================
+
+Existing mailing lists can be deleted through the API, by doing an HTTP
+``DELETE`` on the mailing list URL.
+::
+
+    >>> dump_json('http://localhost:9001/3.0/lists/test-two@example.com',
+    ...           method='DELETE')
+    content-length: 0
+    date: ...
+    server: ...
+    status: 204
+
+    # The above starts a Storm transaction, which will lock the database
+    # unless we abort it.
+    >>> transaction.abort()
+
+The mailing list does not exist.
+
+    >>> print list_manager.get('test-two@example.com')
+    None
+
+You cannot delete a mailing list that does not exist or has already been
+deleted.
+::
+
+    >>> dump_json('http://localhost:9001/3.0/lists/test-two@example.com',
+    ...           method='DELETE')
+    Traceback (most recent call last):
+    ...
+    HTTPError: HTTP Error 404: 404 Not Found
+
+    >>> dump_json('http://localhost:9001/3.0/lists/test-ten@example.com',
+    ...           method='DELETE')
+    Traceback (most recent call last):
+    ...
+    HTTPError: HTTP Error 404: 404 Not Found