← Back to branch summary

~barry/mailman/events-and-web

« back to all changes in this revision

Viewing changes to src/mailman/rest/docs/lists.rst

  • Committer: Barry Warsaw
  • Date: 2012-09-22 15:16:26 UTC
  • mfrom: (7173.1.2 mailman)
  • Revision ID: barry@list.org-20120922151626-76mokawq2hve1cj2
 * 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.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/mailman/rest/docs/lists.rst
23
23
        display_name: Test-one
24
24
        fqdn_listname: test-one@example.com
25
25
        http_etag: "..."
 
26
        list_id: test-one.example.com
26
27
        list_name: test-one
27
28
        mail_host: example.com
28
29
        member_count: 0
29
 
        self_link: http://localhost:9001/3.0/lists/test-one@example.com
 
30
        self_link: http://localhost:9001/3.0/lists/test-one.example.com
30
31
        volume: 1
31
32
    http_etag: "..."
32
33
    start: 0
40
41
        display_name: Test-one
41
42
        fqdn_listname: test-one@example.com
42
43
        http_etag: "..."
 
44
        list_id: test-one.example.com
43
45
        list_name: test-one
44
46
        mail_host: example.com
45
47
        member_count: 0
46
 
        self_link: http://localhost:9001/3.0/lists/test-one@example.com
 
48
        self_link: http://localhost:9001/3.0/lists/test-one.example.com
47
49
        volume: 1
48
50
    http_etag: "..."
49
51
    start: 0
66
68
    ...           })
67
69
    content-length: 0
68
70
    date: ...
69
 
    location: http://localhost:9001/3.0/lists/test-two@example.com
 
71
    location: http://localhost:9001/3.0/lists/test-two.example.com
70
72
    ...
71
73
 
72
74
The mailing list exists in the database.
85
87
 
86
88
It is also available via the location given in the response.
87
89
 
 
90
    >>> dump_json('http://localhost:9001/3.0/lists/test-two.example.com')
 
91
    display_name: Test-two
 
92
    fqdn_listname: test-two@example.com
 
93
    http_etag: "..."
 
94
    list_id: test-two.example.com
 
95
    list_name: test-two
 
96
    mail_host: example.com
 
97
    member_count: 0
 
98
    self_link: http://localhost:9001/3.0/lists/test-two.example.com
 
99
    volume: 1
 
100
 
 
101
Normally, you access the list via its RFC 2369 list-id as shown above, but for
 
102
backward compatibility purposes, you can also access it via the list's posting
 
103
address, if that has never been changed (since the list-id is immutable, but
 
104
the posting address is not).
 
105
 
88
106
    >>> dump_json('http://localhost:9001/3.0/lists/test-two@example.com')
89
107
    display_name: Test-two
90
108
    fqdn_listname: test-two@example.com
91
109
    http_etag: "..."
 
110
    list_id: test-two.example.com
92
111
    list_name: test-two
93
112
    mail_host: example.com
94
113
    member_count: 0
95
 
    self_link: http://localhost:9001/3.0/lists/test-two@example.com
 
114
    self_link: http://localhost:9001/3.0/lists/test-two.example.com
96
115
    volume: 1
97
116
 
98
117
However, you are not allowed to create a mailing list in a domain that does
122
141
``DELETE`` on the mailing list URL.
123
142
::
124
143
 
125
 
    >>> dump_json('http://localhost:9001/3.0/lists/test-two@example.com',
 
144
    >>> dump_json('http://localhost:9001/3.0/lists/test-two.example.com',
126
145
    ...           method='DELETE')
127
146
    content-length: 0
128
147
    date: ...
129
148
    server: ...
130
149
    status: 204
131
150
 
132
 
    # The above starts a Storm transaction, which will lock the database
133
 
    # unless we abort it.
134
 
    >>> transaction.abort()
135
 
 
136
151
The mailing list does not exist.
137
152
 
138
153
    >>> print list_manager.get('test-two@example.com')
139
154
    None
140
155
 
 
156
    # Unlock the database.
 
157
    >>> transaction.abort()
 
158
 
141
159
You cannot delete a mailing list that does not exist or has already been
142
160
deleted.
143
161
::
144
162
 
145
 
    >>> dump_json('http://localhost:9001/3.0/lists/test-two@example.com',
146
 
    ...           method='DELETE')
147
 
    Traceback (most recent call last):
148
 
    ...
149
 
    HTTPError: HTTP Error 404: 404 Not Found
150
 
 
151
 
    >>> dump_json('http://localhost:9001/3.0/lists/test-ten@example.com',
152
 
    ...           method='DELETE')
153
 
    Traceback (most recent call last):
154
 
    ...
155
 
    HTTPError: HTTP Error 404: 404 Not Found
 
163
    >>> dump_json('http://localhost:9001/3.0/lists/test-two.example.com',
 
164
    ...           method='DELETE')
 
165
    Traceback (most recent call last):
 
166
    ...
 
167
    HTTPError: HTTP Error 404: 404 Not Found
 
168
 
 
169
    >>> dump_json('http://localhost:9001/3.0/lists/test-ten.example.com',
 
170
    ...           method='DELETE')
 
171
    Traceback (most recent call last):
 
172
    ...
 
173
    HTTPError: HTTP Error 404: 404 Not Found
 
174
 
 
175
For backward compatibility purposes, you can delete a list via its posting
 
176
address as well.
 
177
 
 
178
    >>> dump_json('http://localhost:9001/3.0/lists/test-one@example.com',
 
179
    ...           method='DELETE')
 
180
    content-length: 0
 
181
    date: ...
 
182
    server: ...
 
183
    status: 204
 
184
 
 
185
The mailing list does not exist.
 
186
 
 
187
    >>> print list_manager.get('test-one@example.com')
 
188
    None