diff options
Diffstat (limited to 'src/mailman/rest/docs/lists.rst')
| -rw-r--r-- | src/mailman/rest/docs/lists.rst | 139 |
1 files changed, 69 insertions, 70 deletions
diff --git a/src/mailman/rest/docs/lists.rst b/src/mailman/rest/docs/lists.rst index 0c4bbc419..5c65a7951 100644 --- a/src/mailman/rest/docs/lists.rst +++ b/src/mailman/rest/docs/lists.rst @@ -14,48 +14,41 @@ yet though. 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 ...> + >>> mlist = create_list('ant@example.com') >>> transaction.commit() >>> dump_json('http://localhost:9001/3.0/lists') entry 0: - display_name: Test-one - fqdn_listname: test-one@example.com + display_name: Ant + fqdn_listname: ant@example.com http_etag: "..." - list_id: test-one.example.com - list_name: test-one + list_id: ant.example.com + list_name: ant 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/ant.example.com volume: 1 http_etag: "..." start: 0 total_size: 1 You can also query for lists from a particular domain. -:: >>> dump_json('http://localhost:9001/3.0/domains/example.com/lists') entry 0: - display_name: Test-one - fqdn_listname: test-one@example.com + display_name: Ant + fqdn_listname: ant@example.com http_etag: "..." - list_id: test-one.example.com - list_name: test-one + list_id: ant.example.com + list_name: ant 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/ant.example.com volume: 1 http_etag: "..." start: 0 total_size: 1 - >>> dump_json('http://localhost:9001/3.0/domains/no.example.org/lists') - Traceback (most recent call last): - ... - HTTPError: HTTP Error 404: 404 Not Found - Creating lists via the API ========================== @@ -64,11 +57,11 @@ 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', + ... 'fqdn_listname': 'bee@example.com', ... }) content-length: 0 date: ... - location: http://localhost:9001/3.0/lists/test-two.example.com + location: http://localhost:9001/3.0/lists/bee.example.com ... The mailing list exists in the database. @@ -78,24 +71,29 @@ The mailing list exists in the database. >>> from zope.component import getUtility >>> list_manager = getUtility(IListManager) - >>> list_manager.get('test-two@example.com') - <mailing list "test-two@example.com" at ...> + >>> bee = list_manager.get('bee@example.com') + >>> bee + <mailing list "bee@example.com" at ...> + +The mailing list was created using the default style, which allows list posts. - # The above starts a Storm transaction, which will lock the database - # unless we abort it. + >>> bee.allow_list_posts + True + +.. Abort the Storm transaction. >>> transaction.abort() -It is also available via the location given in the response. +It is also available in the REST API 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 + >>> dump_json('http://localhost:9001/3.0/lists/bee.example.com') + display_name: Bee + fqdn_listname: bee@example.com http_etag: "..." - list_id: test-two.example.com - list_name: test-two + list_id: bee.example.com + list_name: bee 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/bee.example.com volume: 1 Normally, you access the list via its RFC 2369 list-id as shown above, but for @@ -103,35 +101,52 @@ 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 + >>> dump_json('http://localhost:9001/3.0/lists/bee@example.com') + display_name: Bee + fqdn_listname: bee@example.com http_etag: "..." - list_id: test-two.example.com - list_name: test-two + list_id: bee.example.com + list_name: bee 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/bee.example.com volume: 1 -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 +Apply a style at list creation time +----------------------------------- + +:ref:`List styles <list-styles>` allow you to more easily create mailing lists +of a particular type, e.g. discussion lists. We can see which styles are +available, and which is the default style. + + >>> dump_json('http://localhost:9001/3.0/lists/styles') + default: legacy-default + http_etag: "..." + style_names: ['legacy-announce', 'legacy-default'] -Nor can you create a mailing list that already exists. +When creating a list, if we don't specify a style to apply, the default style +is used. However, we can provide a style name in the POST data to choose a +different style. >>> dump_json('http://localhost:9001/3.0/lists', { - ... 'fqdn_listname': 'test-one@example.com', + ... 'fqdn_listname': 'cat@example.com', + ... 'style_name': 'legacy-announce', ... }) - Traceback (most recent call last): + content-length: 0 + date: ... + location: http://localhost:9001/3.0/lists/cat.example.com ... - HTTPError: HTTP Error 400: Mailing list exists + +We can tell that the list was created using the `legacy-announce` style, +because announce lists don't allow posting by the general public. + + >>> cat = list_manager.get('cat@example.com') + >>> cat.allow_list_posts + False + +.. Abort the Storm transaction. + >>> transaction.abort() Deleting lists via the API @@ -141,7 +156,7 @@ 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/bee.example.com', ... method='DELETE') content-length: 0 date: ... @@ -150,32 +165,16 @@ Existing mailing lists can be deleted through the API, by doing an HTTP The mailing list does not exist. - >>> print list_manager.get('test-two@example.com') + >>> print list_manager.get('bee@example.com') None - # Unlock the database. +.. Abort the Storm transaction. >>> 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', - ... 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 - 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', + >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com', ... method='DELETE') content-length: 0 date: ... @@ -184,5 +183,5 @@ address as well. The mailing list does not exist. - >>> print list_manager.get('test-one@example.com') + >>> print list_manager.get('ant@example.com') None |