Improve discoverability of MediaWiki API
Open, NormalPublic

Description

Figuring out whether and where MediaWiki API providess what you want is difficult. T75952 mentions discovering the message list and the interwiki list, but this assumes the developer even knows these terms, and the strings "interwiki" and "message" appear all over the help.

Some ideas:

Generated API help

  • T89659: Give action=query higher billing on api main help page
  • T75952: Add more prominent "single page" link to api.php
  • Generated API help could use a TOC and/or collapsible sections, especially with the sprawling single-page recursivesubmodules=1 mode.
    • either change the action and submodule headings (e.g. "prop=pageimages (pi)" to be more informative with a blurb, or when collapsed continue to show the description underneath.
  • Implement an action=help mode that shows a recursive list of actions and submodules with only their titles (h2 heading contents like "prop=pageimages (pi)") and descriptions (api-xxx-description messages).
    • The apihelp-linktrail line that displays e.g. "(main | query | imageusage)" could have a link to this.
  • The possible action, prop, list, and meta values currently display as a long comma-separated list the same as any other parameter value. Instead they could show a blurb/description of what they do, appear as a bulleted list, etc.
  • Implement a specialized search of the generated API help that favors words in the action/submodule description.

ApiSandbox

Here all you have is dropdown lists for action and query submodule. It needs ways to explore and search the descriptions of API actions and submodules.

on-wiki

Spage updated the task description. (Show Details)
Spage raised the priority of this task from to Needs Triage.
Spage added subscribers: Spage, MZMcBride.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMay 12 2015, 7:39 PM
Spage updated the task description. (Show Details)May 12 2015, 8:04 PM
Spage set Security to None.
Anomie added a subscriber: Anomie.May 12 2015, 8:28 PM
  • Generated API help could use a TOC and/or collapsible sections, especially with the sprawling single-page recursivesubmodules=1 mode.

TOC was fixed in Gerrit change 209282. Although it currently doesn't show by default.

  • either change the action and submodule headings (e.g. "prop=pageimages (pi)" to be more informative with a blurb, or when collapsed continue to show the description underneath.

Shoving blurbs into section headings seems likely that it'd give you a TOC that was an unreadable wall of text.

  • Implement an action=help mode that shows a recursive list of actions and submodules with only their titles (h2 heading contents like "prop=pageimages (pi)") and descriptions (api-xxx-description messages).

Such a parameter is doable easily enough, but I'd be a bit worried about parameter clutter.

  • The apihelp-linktrail line that displays e.g. "(main | query | imageusage)" could have a link to this.

And UI clutter. Especially since you suggested in T75952#1280673 to add something different to this line already.

  • The possible action, prop, list, and meta values currently display as a long comma-separated list the same as any other parameter value. Instead they could show a blurb/description of what they do, appear as a bulleted list, etc.

That would make for a very long parameter listing. The current comma-separated list is already rather long.

  • Implement a specialized search of the generated API help that favors words in the action/submodule description.

That seems like it's getting outside the scope of the API itself, into the realm of Special:Search.

ApiSandbox

Here all you have is dropdown lists for action and query submodule. It needs ways to explore and search the descriptions of API actions and submodules.

Not that I think it'll improve your view of it much, but here's the WIP rewrite. "Explore" would probably want some sort of custom oojs-ui widget, while I have no idea about "search" since you'd probably want out-of-context searching going on there.

Spage triaged this task as Normal priority.Jul 28 2015, 5:26 AM
Qgil added a subscriber: Qgil.Jul 28 2015, 6:00 AM
Qgil moved this task from Backlog to Team radar on the Developer-Advocacy board.

@srishakatux and I were discussing changing the name for https://www.mediawiki.org/wiki/API:Main_page to MediaWiki Action API to more accurately reflect the content. Are there any thoughts or alternate suggestions.

bd808 added a subscriber: bd808.Fri, Aug 31, 8:19 PM

@srishakatux and I were discussing changing the name for https://www.mediawiki.org/wiki/API:Main_page to MediaWiki Action API to more accurately reflect the content. Are there any thoughts or alternate suggestions.

The redirect https://www.mediawiki.org/w/index.php?title=Action_API&redirect=no exists today. Making another redirect at https://www.mediawiki.org/wiki/MediaWiki_Action_API seems uncontroversial. I'm not sure about moving the content actually outside of the API namespace. Are you hoping for SEO boost in internal search or external? Do we know how wiki redirects are indexed by major search engines if the desire is for external SEO?

srodlund added a comment.EditedFri, Aug 31, 9:00 PM

I believe it is still our intent to keep it in the API namespace: API: MediaWiki Action API . This is a suggested title -- so any feedback is welcome.

In this case, we weren't discussing SEO as a main driver (internal or external) for the choice, but more about having a title that is a more accurate reflection of the content of the page, one that separates it from the other those covered in the Web APIs Hub.

The API Main Page is currently the top result in a simple Google search for the keyword phrase: "MediaWiki Action API". Whether this will change once the new (more minimal) content is indexed or whether the historical content will play some role in future indexing is hard to know through a casual guess. There is some (disputed) thinking that headings influence search ranking in Google; it's possible that a title that more accurately reflects the content on the page would have a positive effect on external searches. That said -- I don't know specifically how individual external search engines handle headings or content on MediaWiki and don't want to make any claim without the data ;-) If external (or internal) ranking is important, we can make some observations and subtle changes over time to see what works better.

Qgil removed a subscriber: Qgil.Mon, Sep 3, 9:08 AM
bd808 added a comment.Tue, Sep 11, 6:05 PM

I believe it is still our intent to keep it in the API namespace: API: MediaWiki Action API . This is a suggested title -- so any feedback is welcome.

Renaming https://www.mediawiki.org/wiki/API:Main_page to https://www.mediawiki.org/wiki/API:MediaWiki_Action_API (and leaving a redirect for the old title) seems fine to me. There will be a large number of existing links to clean up to reduce the use of the redirect following the rename. There are pywikibot scripts that can be used to help with this effort.