Change #1235368 had a related patch set uploaded (by DLynch; author: DLynch):

[mediawiki/extensions/DiscussionTools@master] ApiDiscussionToolsPageInfo: add a new overview prop for top-level info

https://gerrit.wikimedia.org/r/1235368

This would save us time and effort in T402781 - do you know if/when this could be merged?

I'm trying to round up a reviewer for it.

Change #1235368 merged by jenkins-bot:

[mediawiki/extensions/DiscussionTools@master] ApiDiscussionToolsPageInfo: add a new overview prop for top-level info

https://gerrit.wikimedia.org/r/1235368

This can now be seen on the beta cluster, e.g. https://en.wikipedia.beta.wmcloud.org/wiki/Special:ApiSandbox#action=discussiontoolspageinfo&format=json&page=Talk%3AMain_Page&prop=overview&formatversion=2

It adds a new prop to discussiontoolspageinfo called overview produces output that's basically a very shallow version of the existing threaditemshtml prop.

The differences are:

• It only provides the top-level headings, without the full replies key that contains the comment tree -- instead it just contains the IDs of the top-level comments (which, because of how DiscussionTools works, is probably going to just be one single ID representing the initial post by the topic-starter)
• There is no html key containing the post's contents
• Instead of a latestReplyTimestamp field, it has a full latestReply that contains a serialized reply object for the last response to the thread.

A sample:

{
  "discussiontoolspageinfo": {
    "overview": [
      {
        "headingLevel": 2,
        "name": "h-Medelam-2021-10-19T13:49:00.000Z",
        "type": "heading",
        "level": 0,
        "id": "h-Badminton_module-2021-10-19T13:49:00.000Z",
        "replies": [
          "c-Medelam-2021-10-19T13:49:00.000Z-Badminton_module"
        ],
        "title": "Badminton module",
        "commentCount": 5,
        "authorCount": 2,
        "latestReply": {
          "timestamp": "2021-10-19T15:18:00Z",
          "author": "Jts1882",
          "type": "comment",
          "level": 5,
          "id": "c-Jts1882-2021-10-19T15:18:00.000Z-Medelam-2021-10-19T14:44:00.000Z"
        },
        "timestamp": "2021-10-19T13:49:00Z"
      },
      {
        "headingLevel": 2,
        "name": "h-Curb_Safe_Charmer-2021-10-19T16:54:00.000Z",
        "type": "heading",
        "level": 0,
        "id": "h-Looking_for_help_from_a_Python_dev_to_help_getting_ReFill_to_build_and_run-2021-10-19T16:54:00.000Z",
        "replies": [
          "c-Curb_Safe_Charmer-2021-10-19T16:54:00.000Z-Looking_for_help_from_a_Python_dev_to_help_getting_ReFill_to_build_and_run"
        ],
        "title": "Looking for help from a Python dev to help getting ReFill to build and run",
        "commentCount": 4,
        "authorCount": 2,
        "latestReply": {
          "timestamp": "2021-10-19T20:09:00Z",
          "author": "TheresNoTime",
          "type": "comment",
          "level": 4,
          "id": "c-TheresNoTime-2021-10-19T20:09:00.000Z-Curb_Safe_Charmer-2021-10-19T20:06:00.000Z"
        },
        "timestamp": "2021-10-19T16:54:00Z"
      },
    ],
  },
}

This is behaving as documented.

On reflection I think we maybe should make the response closer to threaditemshtml. Discussing with engineers.

Change #1240772 had a related patch set uploaded (by DLynch; author: DLynch):

[mediawiki/extensions/DiscussionTools@master] ApiDiscussionToolsPageInfo: Collapse overview into modifiers to threaditemshtml

https://gerrit.wikimedia.org/r/1240772

Change #1240772 merged by jenkins-bot:

[mediawiki/extensions/DiscussionTools@master] ApiDiscussionToolsPageInfo: Collapse overview into modifiers to threaditemshtml

https://gerrit.wikimedia.org/r/1240772

Okay, update to what's happening. There is now not a new prop. Instead the existing threaditemshtml prop has been modified to listen to a new parameter called threaditemsflags, which can contain activity, noreplies, and excludesignatures (related to that: the existing excludesignatures param has been deprecated and moved into this).

The effects of these flags are:

• activity: a latestReply and oldestReply item will be added to headings, which will contain a serialized reply object for the most recent and oldest replies. Oldest will almost-certainly be the initial post that started the thread, but people can play games with timestamps if they really want to.
• noreplies: strips the replies field from the headings (which removes most of the bulk from this API endpoint that made it unsuitable for the quick-summary cases we're trying to support here)
• excludesignatures has the same effect as the existing param, and controls whether the html field in a comment contains the signature. (Which shouldn't affect the uses here, since noreplies means you won't be getting comment-HTML.)

The notable practical difference is

1. the headings will contain a html field that contains the rendered text rather than a title field that stripped markup.
2. there will be a placeholder heading for the lead section if it exists on the page with content even if it doesn't contain any replies; it's detectable by looking for "headingLevel": null,. It will have an othercontent key that will include the HTML that makes up the lead section.

Example output for a given heading will be like the following from https://en.wikipedia.beta.wmcloud.org/wiki/Special:ApiSandbox#action=discussiontoolspageinfo&format=json&page=Talk%3AMain_Page&prop=threaditemshtml&threaditemsflags=activity%7Cnoreplies&formatversion=2 :

{
    "headingLevel": 2,
    "name": "h-Medelam-2021-10-19T13:49:00.000Z",
    "type": "heading",
    "level": 0,
    "id": "h-Badminton_module-2021-10-19T13:49:00.000Z",
    "html": "Badminton module",
    "commentCount": 5,
    "authorCount": 2,
    "latestReplyTimestamp": "2021-10-19T15:18:00Z",
    "latestReply": {
        "timestamp": "2021-10-19T15:18:00Z",
        "author": "Jts1882",
        "type": "comment",
        "level": 5,
        "id": "c-Jts1882-2021-10-19T15:18:00.000Z-Medelam-2021-10-19T14:44:00.000Z"
    },
    "oldestReply": {
        "timestamp": "2021-10-19T13:49:00Z",
        "author": "Medelam",
        "type": "comment",
        "level": 1,
        "id": "c-Medelam-2021-10-19T13:49:00.000Z-Badminton_module"
    }
},

Thanks for the update! I'll change my code and API call to adapt to the new format.

Working as specified

@DLynch: have we documented the existence of this API on mediawiki yet (e.g. somewhere on mw:Extension:DiscussionTools? If not, could you please do so? I'm thinking that, for now, the mention we make could be as simple as a sentence that links back to this task.

@ppelberg in a sense -- it's the "discussiontoolspageinfo" row in this table:

With this change we might want to actually remove the "internal" flag from it.

In T416038#11654967, @DLynch wrote:

@ppelberg in a sense -- it's the "discussiontoolspageinfo" row in this table:

What do you think about updating this task description with the content of T416038#11625576 and linking discussiontoolspageinfo to this ticket?

In T416038#11654973, @DLynch wrote:

With this change we might want to actually remove the "internal" flag from it.

I defer to you + the rest of the Editing Engineering Team to make this call.

We may want to address T418536 as well, because there's pages out there whose structure causes our current API to do unintuitive things.

In T416038#11656385, @ppelberg wrote:

In T416038#11654967, @DLynch wrote:

@ppelberg in a sense -- it's the "discussiontoolspageinfo" row in this table:

What do you think about updating this task description with the content of T416038#11625576 and linking discussiontoolspageinfo to this ticket?

In T416038#11654973, @DLynch wrote:

With this change we might want to actually remove the "internal" flag from it.

I defer to you + the rest of the Editing Engineering Team to make this call.

I went ahead and made these changes (update task description, update https://www.mediawiki.org/wiki/Extension:DiscussionTools#Editing); I think that wraps up this task but feel free to reopen if I've missed something!