diff options
| author | Barry Warsaw | 2015-12-17 17:41:49 -0500 |
|---|---|---|
| committer | Barry Warsaw | 2015-12-17 17:41:49 -0500 |
| commit | 21062456bb4707398157b8ce5b6f741e1ef6ebbc (patch) | |
| tree | f62fde15c92589aef8aeaf60ff68c449df2a0fe6 /src/mailman/rest/docs/listconf.rst | |
| parent | e5422f5316335e8cae5dae3965417bb317e057e3 (diff) | |
| download | mailman-21062456bb4707398157b8ce5b6f741e1ef6ebbc.tar.gz mailman-21062456bb4707398157b8ce5b6f741e1ef6ebbc.tar.zst mailman-21062456bb4707398157b8ce5b6f741e1ef6ebbc.zip | |
Many improvements to listconf.py.
Closes #182
* Improve the documentation, especially in describing how to PUT and
PATCH to list configuration subresources.
* Improve the return codes for many error corner cases. Specifically,
this makes more consistent when a 400 error is returned or a 404 error
is returned.
* Improve the handling of some weird corner cases, and add tests.
* Fix the setting of error response reasons by not trying to .format()
into a bytes object (which isn't allowed in Python 3).
* Add lots of comments to the code, which improves the readability of
all the twisty little turns.
* 100% code coverage for listconf.py!
Diffstat (limited to 'src/mailman/rest/docs/listconf.rst')
| -rw-r--r-- | src/mailman/rest/docs/listconf.rst | 54 |
1 files changed, 50 insertions, 4 deletions
diff --git a/src/mailman/rest/docs/listconf.rst b/src/mailman/rest/docs/listconf.rst index bcf4f856e..319028be5 100644 --- a/src/mailman/rest/docs/listconf.rst +++ b/src/mailman/rest/docs/listconf.rst @@ -186,10 +186,56 @@ These values are changed permanently. Sub-resources ============= -Many of the mailing list configuration variables are actually available as -sub-resources on the mailing list. This is because they are collections, -sequences, and other complex configuration types. Their values can be -retrieved and set through the sub-resource. +Mailing list configuration variables are actually available as sub-resources +on the mailing list. Their values can be retrieved and set through the +sub-resource. + + +Simple resources +---------------- + +You can view the current value of the sub-resource. + + >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com' + ... '/config/display_name') + display_name: My List + http_etag: ... + +The resource can be changed by PUTting to it. Note that the value still +requires a dictionary, and that dictionary must have a single key matching the +name of the resource. +:: + + >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com' + ... '/config/display_name', + ... dict(display_name='Your List'), + ... 'PUT') + content-length: 0 + date: ... + server: ... + status: 204 + + >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com' + ... '/config/display_name') + display_name: Your List + http_etag: ... + +PATCH works the same way, with the same effect, so you can choose to use +either method. + + >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com' + ... '/config/display_name', + ... dict(display_name='Their List'), + ... 'PATCH') + content-length: 0 + date: ... + server: ... + status: 204 + + >>> dump_json('http://localhost:9001/3.0/lists/ant.example.com' + ... '/config/display_name') + display_name: Their List + http_etag: ... Acceptable aliases |