We need to understand which API functions to use for creating and managing Gather collections, starting with the "fixed" collection of saved pages. We'll need API calls to do the following:
In ApiSandbox check out action=query: list=lists, list=listpages, and prop=listmembership; action=editlist.
All edit operations are POST requests to the same URI and require a watch token, and probably cookies, too. If you want to try this in the browser you'll want to change the token to get one you've actually got; same for the list ID.
To retrieve a token you can use the following request:
Request URL: https://en.m.wikipedia.org/w/api.php?action=editlist&format=json
POST data: label=Saved%20pages&perm=private&titles=A%7Cthrough%7CZ&token=9a235a7e1d917a543f9787dc77cde1c556997ab9%2B%5C
Response:
{
"batchcomplete": "",
"editlist": {
"status": "created",
"id": 25875,
"pages": [
{
"title": "A",
"added": ""
},
{
"title": "through",
"added": ""
},
{
"title": "Z",
"added": ""
}
]
}
}Request URL: https://en.m.wikipedia.org/w/api.php?action=editlist&format=json
POST data: id=25875&mode=update&titles=Rock%7COn&token=9a235a7e1d917a543f9787dc77cde1c556997ab9%2B%5C
Response:
{
"batchcomplete": "",
"editlist": {
"status": "nochanges",
"id": 25875,
"pages": [
{
"title": "On",
"added": ""
},
{
"title": "Rock",
"added": ""
}
]
}
}Request URL: https://en.m.wikipedia.org/w/api.php?action=editlist&format=json
POST data: id=25875&mode=remove&titles=Rock%7COn&token=9a235a7e1d917a543f9787dc77cde1c556997ab9%2B%5C
Response:
{
"batchcomplete": "",
"editlist": {
"status": "nochanges",
"id": 25875,
"pages": [
{
"title": "On",
"removed": ""
},
{
"title": "Rock",
"removed": ""
}
]
}
}Request URL: https://en.m.wikipedia.org/w/api.php?action=editlist&format=json
POST data: id= 25875&mode=deletelist&token=9a235a7e1d917a543f9787dc77cde1c556997ab9%2B%5C
Response:
{
"editlist": {
"status": "deleted",
"id": 25875
}
}We can also add a description to lists.
Gather API automatically sets a list image if the first page has one. It's probably easiest to just take advantage of that initially, and not try to tackle the up to four thumbnails combination to get it done faster.
Let's try to use Retrofit from the start.
Watchlist always has id 0. We might want to consider defining a special list id for saved pages and history.
Saved pages could be -1. Or something like that. I think this could make it easier for the app considering that list names should be localized and until we have an offline flag in the API.
Longer term, it would be good to also add the offline flag to the DB schema and the API, so a user could add more than one collection for pages which are saved on the device for offline reading, to better organize saved pages.
The problem is that the API doesn't currently allow an/this ID to be set when creating a new list:
"code": "badid", "info": "List id was not found",
There doesn't seem to be support for cross-wiki collections. Collections seem to be able to hold pages of the local wiki only. While this might be acceptable for web at first thought this is not enough for the app. A case could be made that this would also benefit web considering the completed SUL effort.
Potential workarounds:
In both cases it would be complicated to have collections which contain pages from multiple wikis. In the UI design it would be good to group any collection by wiki.
It is currently only deployed on enwiki and hewiki. This means that for the saved pages feature we could only save the list of pages from these wikis but not pages on other wikis. That would be an inconsistent user experience.
I'm not convinced cross-wiki lists fit well into the Gather (or even action API) use case. Sure, we could add interwiki prefixes to Gather lists, maybe even move all lists into some central database; but if you want to load any information about those articles lists (such as lead images or text extracts or last edit dates), you would have to make API queries to multiple wikis anyway. Maybe in the future T91162: RFC: Shadow namespaces might enable easier cross-referencing between wikis.
Watchlists have a "virtual" ID since they are actually stored in a different table. It's an ugly hack that I would rather not build upon. Real list IDs are not per-user. That said, adding some kind of "role flag" to lists and selecting them based on that does not seem to be problematic.
will keep this open, and in Tracking, for reference purposes until we complete the implementation.
discussion taking place at https://www.mediawiki.org/wiki/User:DBrant_(WMF)/Gather_on_Android