diff options
| -rw-r--r-- | src/mailman/rest/docs/collections.rst | 88 | ||||
| -rw-r--r-- | src/mailman/rest/docs/helpers.rst | 2 |
2 files changed, 89 insertions, 1 deletions
diff --git a/src/mailman/rest/docs/collections.rst b/src/mailman/rest/docs/collections.rst new file mode 100644 index 000000000..09310f226 --- /dev/null +++ b/src/mailman/rest/docs/collections.rst @@ -0,0 +1,88 @@ +============================ + Collections and Pagination +============================ + +All collections automatically support pagination. You can use this to limit +the number of items of the collection that get returned, and you can page +through the results by incrementing the page counter. + +For example, let's say we have 50 mailing lists. + + >>> from mailman.app.lifecycle import create_list + >>> for i in range(50): + ... mlist = create_list('list{:02d}@example.com'.format(i)) + >>> transaction.commit() + +We can get the first 10 lists by asking for the first page of items. + + >>> json = call_http('http://localhost:9001/3.0/lists?count=10&page=1') + >>> for entry in json['entries']: + ... print(entry['list_id']) + list00.example.com + list01.example.com + list02.example.com + list03.example.com + list04.example.com + list05.example.com + list06.example.com + list07.example.com + list08.example.com + list09.example.com + +We can also ask for the third set of 10 mailing lists. + + >>> json = call_http('http://localhost:9001/3.0/lists?count=10&page=3') + >>> for entry in json['entries']: + ... print(entry['list_id']) + list20.example.com + list21.example.com + list22.example.com + list23.example.com + list24.example.com + list25.example.com + list26.example.com + list27.example.com + list28.example.com + list29.example.com + +Of course, we can also adjust the page size and ask for the tenth page of 5 +mailing lists. + + >>> json = call_http('http://localhost:9001/3.0/lists?count=5&page=10') + >>> for entry in json['entries']: + ... print(entry['list_id']) + list45.example.com + list46.example.com + list47.example.com + list48.example.com + list49.example.com + + +The size of a collection +======================== + +This same idiom allows you to get just the size of the collection. You do +this by asking for a page of size zero. + + >>> dump_json('http://localhost:9001/3.0/lists?count=0&page=1') + http_etag: ... + start: 0 + total_size: 50 + + +Page start +========== + +Notice the `start` element in the returned JSON. This tells you which item of +the collection the page starts on. + + >>> dump_json('http://localhost:9001/3.0/lists?count=2&page=15') + entry 0: + display_name: List28 + ... + entry 1: + display_name: List29 + ... + http_etag: ... + start: 28 + total_size: 50 diff --git a/src/mailman/rest/docs/helpers.rst b/src/mailman/rest/docs/helpers.rst index 36870c079..61e2ecec6 100644 --- a/src/mailman/rest/docs/helpers.rst +++ b/src/mailman/rest/docs/helpers.rst @@ -121,7 +121,7 @@ But if the optional values are present, they must of course also be valid. Arrays ------- +====== Some ``POST`` forms include more than one value for a particular key. This is how lists and arrays are modeled. The validator does the right thing with |