Page MenuHomePhabricator

[Spike] Research the correct API calls to use for managing Gather collections for saved pages.
Closed, ResolvedPublic

Description

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:

  • Create a new (empty) collection for a logged-in user.
  • Add an article (or multiple articles?) to a collection.
  • Delete an article (or multiple articles) from a collection.
  • Delete a collection.

Event Timeline

Dbrant created this task.Jan 12 2016, 4:25 PM
Dbrant raised the priority of this task from to Needs Triage.
Dbrant updated the task description. (Show Details)
Dbrant moved this task to Current Sprint on the Wikipedia-Android-App-Backlog board.
Dbrant added a subscriber: Dbrant.
Restricted Application added subscribers: StudiesWorld, Aklapper. · View Herald TranscriptJan 12 2016, 4:25 PM
bearND set Security to None.
bearND moved this task from To Do to Doing on the Mobile-App-Android-Sprint-73-Tantalum board.

API docs

In ApiSandbox check out action=query: list=lists, list=listpages, and prop=listmembership; action=editlist.

Example API calls we may need

Read only

Edit

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:

  • Create list and add pages at the same time: (sandbox)
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
    }
}

More info/docs

Extras goodies / thoughts about implementation

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.

What we still need from the API

A new specified list ID for saved pages

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",

Support for cross-wiki lists

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:

  • We could work around this issue if there was a way to store a list of wikis which the current user has collections on. Then the app would ask every wiki in that list of wikis of its collections. This is not the best dev experience, and extra requests are needed. I hope there is a better way.
  • We could ask the user right after first login which wikis she has any collections stored. This is worse UX IMO.

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.

Gather extension deployed on every WP 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.

Tgr added a subscriber: Tgr.Jan 17 2016, 4:55 AM

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.

Dbrant closed this task as Resolved.Jan 18 2016, 3:46 PM
Dbrant reopened this task as Open.Jan 18 2016, 3:48 PM

will keep this open, and in Tracking, for reference purposes until we complete the implementation.

Dbrant closed this task as Resolved.Apr 11 2016, 2:40 PM

:..(