* Add list_id to JSON representation for a mailing list (given by Jimmy

   Bergman).
 * The canonical resource for a mailing list (and thus its self_link) is now
   the URL with the list-id.  To reference a mailing list, the list-id url is
   preferred, but for backward compatibility, the posting address is still
   accepted.

1 files changed, 44 insertions, 11 deletions

diff --git a/src/mailman/rest/docs/lists.rst b/src/mailman/rest/docs/lists.rst
index 610244968..0c4bbc419 100644
--- a/src/mailman/rest/docs/lists.rst
+++ b/src/mailman/rest/docs/lists.rst
@@ -23,10 +23,11 @@ Create a mailing list in a domain and it's accessible via the API.
         display_name: Test-one
         fqdn_listname: test-one@example.com
         http_etag: "..."
+        list_id: test-one.example.com
         list_name: test-one
         mail_host: example.com
         member_count: 0
-        self_link: http://localhost:9001/3.0/lists/test-one@example.com
+        self_link: http://localhost:9001/3.0/lists/test-one.example.com
         volume: 1
     http_etag: "..."
     start: 0
@@ -40,10 +41,11 @@ You can also query for lists from a particular domain.
         display_name: Test-one
         fqdn_listname: test-one@example.com
         http_etag: "..."
+        list_id: test-one.example.com
         list_name: test-one
         mail_host: example.com
         member_count: 0
-        self_link: http://localhost:9001/3.0/lists/test-one@example.com
+        self_link: http://localhost:9001/3.0/lists/test-one.example.com
         volume: 1
     http_etag: "..."
     start: 0
@@ -66,7 +68,7 @@ New mailing lists can also be created through the API, by posting to the
     ...           })
     content-length: 0
     date: ...
-    location: http://localhost:9001/3.0/lists/test-two@example.com
+    location: http://localhost:9001/3.0/lists/test-two.example.com
     ...
 
 The mailing list exists in the database.
@@ -85,14 +87,31 @@ The mailing list exists in the database.
 
 It is also available via the location given in the response.
 
+    >>> dump_json('http://localhost:9001/3.0/lists/test-two.example.com')
+    display_name: Test-two
+    fqdn_listname: test-two@example.com
+    http_etag: "..."
+    list_id: test-two.example.com
+    list_name: test-two
+    mail_host: example.com
+    member_count: 0
+    self_link: http://localhost:9001/3.0/lists/test-two.example.com
+    volume: 1
+
+Normally, you access the list via its RFC 2369 list-id as shown above, but for
+backward compatibility purposes, you can also access it via the list's posting
+address, if that has never been changed (since the list-id is immutable, but
+the posting address is not).
+
     >>> dump_json('http://localhost:9001/3.0/lists/test-two@example.com')
     display_name: Test-two
     fqdn_listname: test-two@example.com
     http_etag: "..."
+    list_id: test-two.example.com
     list_name: test-two
     mail_host: example.com
     member_count: 0
-    self_link: http://localhost:9001/3.0/lists/test-two@example.com
+    self_link: http://localhost:9001/3.0/lists/test-two.example.com
     volume: 1
 
 However, you are not allowed to create a mailing list in a domain that does
@@ -122,34 +141,48 @@ 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',
+    >>> 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
 
+    # Unlock the database.
+    >>> transaction.abort()
+
 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',
+    >>> 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',
+    >>> 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
+
+For backward compatibility purposes, you can delete a list via its posting
+address as well.
+
+    >>> dump_json('http://localhost:9001/3.0/lists/test-one@example.com',
+    ...           method='DELETE')
+    content-length: 0
+    date: ...
+    server: ...
+    status: 204
+
+The mailing list does not exist.
+
+    >>> print list_manager.get('test-one@example.com')
+    None