Talk:Core Platform Team/Initiative/Core REST API in MediaWiki/Epics, User Stories, and Requirements

About this board

Administrator -> Moderator

1
EProdromou (WMF) (talkcontribs)

I was having problems with disambiguating between the Administrator persona in these user stories and the Administrator security role on many Wikimedia wikis, as well as the common use of Administrator meaning someone who manages the installation, configuration and maintenance of the wiki software. So, I changed it to "Moderator". At least in Wikimedia wikis, there are many non-admin users who perform moderation tasks.

Reply to "Administrator -> Moderator"

Epic 1, User Story 1

1
EProdromou (WMF) (talkcontribs)

Per discussion with Tim and Corey last night, we realized that there are some finer-grained user stories that require different solutions. I'm going to separate it into three different user stories.

  • Reader reads a page offline. This is the most basic use case, retrieving the metadata about the page and the page text in HTML form in a single request.
  • Reader reads a page online. Downloading a large document encoded in JSON, then loading the HTML from the JSON into a browser or native HTML widget, is much less efficient that letting the browser or widget download the HTML itself. So, if the user is "online", we want to have two endpoints: one for the JSON representation of the page without HTML, and one for HTML only.
  • Contributor gets a page for editing. For a contributor, it's important to get the wikitext source for a page, which can be edited and then updated (user story 3). Because this representation is so similar to the representation for the Create and Update stories, it makes sense to keep this at the GET /page/{title} endpoint.

I'm going to update the user stories to include this information.

Reply to "Epic 1, User Story 1"

Missing the preview use case

3
Phuedx (WMF) (talkcontribs)

There exist a couple of clients that fetch previews of pages that I know of. The iOS app shows a preview if you long press a link IIRC and Page Previews shows a preview if you hover over a link.


When Page Previews was deployed to all of the Wikipedias, we understood that we were introducing a different way to interact with their content. We instrumented that interaction in such a way that it could be reported on like the more traditional pageview interaction. We call this interaction a virtual pageview. In August there were 15.7 billion pageviews and 1.6 billion virtual pageviews by users (see the description of the agent_type column at https://wikitech.wikimedia.org/wiki/Analytics/Data_Lake/Traffic/Webrequest#wmf.webrequest) across all projects.


Please consider adding this use case into epic #1, either by folding it into use case 1 or adding a distinct one, e.g.


As a Reader, I want to get a preview of a page so that I can use the additional information to help me better understand a subject.

As a Reader, I want to get a preview of a page so that I can make a quick, informed decision about jumping into a topic related to a subject.

EProdromou (WMF) (talkcontribs)

These are really good user stories. I wasn't aware of the scale of page previews. AMAZING.

I don't think any of the other user stories in this "Core REST API" are implemented as extensions currently (but I haven't checked against that very carefully). Does it make sense to instead have the Extension:Popups provide these routes?

Phuedx (WMF) (talkcontribs)

That's a great point, @EProdromou (WMF). It'd be a boon to have the definition of a page preview and the viewer of that preview be defined in one place.


It makes, therefore, sense to keep this use case distinct from the Core REST API in MediaWiki despite it being a core method of interaction.

Reply to "Missing the preview use case"

Access-Control-Allow-Origin

3
DBarratt (WMF) (talkcontribs)

I think a requirement should be that the Access-Control-Allow-Origin header is given a default value of * for wikis that are not on an intranet (i.e. behind a firewall). It is completely safe to set this as the default value. MediaWiki should allow this behavior to be disabled if you are running MediaWiki on an intranet.

Doing this will provide for a much better developer experience as developers will be able to use the API from another origin automatically.

See related task T210790.

EProdromou (WMF) (talkcontribs)

David, I'm angry at you for making me think about CORS.

As far as I can tell, you're right and this makes sense for the new Core REST API, especially if we don't allow session cookie authorization.

Do you want to add a ticket as a child of T229661 or should I?

DBarratt (WMF) (talkcontribs)
Reply to "Access-Control-Allow-Origin"

Should the API be stateless?

3
DBarratt (WMF) (talkcontribs)

Instead of allowing a client to login to the server with a session, perhaps it would be better if the API was stateless. This would prevent the need to have CSRF tokens. The client would instead send an Authorization header with each request. Additionally, this would allow a client on a different origin to make authenticated, cross-origin requests (by allowing such requests with the Access-Control-Allow-Credentials header).

EProdromou (WMF) (talkcontribs)

I think our intention for the Core REST API is to use only OAuth 1.0 and 2.0 for authorization. I am really leery of session cookies for APIs, and I'd like to avoid them.

It makes in-browser apps like user gadgets more complex (we have to figure out how to pass OAuth tokens to the browser client), but reduces the impact of other kinds of attacks.

DBarratt (WMF) (talkcontribs)

💯

Reply to "Should the API be stateless?"

Some ideas from the Mobile Contributions Workflow Research

2
CMadeo (WMF) (talkcontribs)

From Mobile contribution research


References

Return the reference / citations list so that curating users can easily review these external links, also potentially useful for some reading focused features


Tagging

Allow users to tag a page/section as needing: general cleanup, copyediting, tone adjustment, structure changes, content removed, more context, expansion, clarity, more balance, more referencing, better categories


User to user communication

Thank a user for their contribution and manually welcome a user

EProdromou (WMF) (talkcontribs)

Wow. Great functionality. How do you feel about these user stories?

- As a Curator, I want to get a list of all references for a page, so I can evaluate the reliability of the text and view the sources directly.

- As a Curator, I want to propose editorial tasks for a page, so I can share my evaluation of the page status with other Curators.

- As a Reader, I want to thank a user for a contribution, so that I can show Contributors that their work matters to me.

- As an Administrator, I want to welcome a user, so that they get some initial information about the project and they know where to look for more information.

(Note that the "Administrator" persona in these use cases is anyone who concerns themselves with the project community, and not necessarily someone with administrator group rights.)

Reply to "Some ideas from the Mobile Contributions Workflow Research"
There are no older topics