Page MenuHomePhabricator

List inherited parameters in MediaWiki API help pages
Open, Needs TriagePublic

Description

Problem

API help pages, such as https://www.wikidata.org/w/api.php?action=help&modules=wbsearchentities, do not actually list all the parameters supported by the API. For instance, the uselang parameter is not listed there, since it applies to all of MediaWiki and is not specific to this action. Similarly, the format parameter controls API output format in general and is therefore not listed there either.

As a user, these parameters are very hard to discover: see for instance this question, which I remember asking myself too: https://lists.wikimedia.org/pipermail/wikidata/2020-October/014339.html
The action documentation gives the impression that it lists all the parameters it accepts, which is a problem.

Proposed solution

If there are few such generic parameters, it could be worth including them in all API help pages, perhaps in a different section. If there are too many of them, there should be a prominent link to a page listing them.

For inspiration, consider treating these implied parameters like inherited members of classes in oriented-object programming. For instance, if I look up the documentation of the "QAudioInput" class in Qt, I find by default only the direct members of that class, but there is a prominent link "List of all members, including inherited members" that I can use to see the inherited ones too.

Event Timeline

Pintoch created this task.Oct 16 2020, 3:43 PM
Restricted Application added a project: Platform Engineering. · View Herald TranscriptOct 16 2020, 3:43 PM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
Tgr added a subscriber: Tgr.Oct 17 2020, 1:00 AM

This would be a bad idea; there is a huge amount of "inherited" parameters, it would make the help page unreadable, and many relevant parameters aren't really inherited (e.g. you can use various extra formatting parameters depending on what value you send for format - those are parameters of the respective format module). For someone unfamiliar with the API, Special:ApiSandbox is probably more useful than Special:ApiHelp.

In that case, then just on that wbsearchentities page I think having a single sentence about "userlang" and providing the link to the other page would help like hell for all those users that have asked in the last year alone. As an institution of holding the worlds knowledge in many languages then "userlang" is probably the most important parameter to let users know about especially given the frame of reference here when we are talking about THE Search API that so many eventually land upon using and building around it.

Make a quick sentence...provide a link to the other page. Done. Close this issue. Gets my vote.

@Tgr how about adding a single link to a page giving some information about this huge amount of "inherited" parameters? That would not make the help page less readable, would it?

Tgr added a comment.Oct 17 2020, 9:38 AM

There is a navigation link to the parent module, but I guess it is not very clear what that is for. A "see here for parameters provided by the parent module" link would make sense. Although in general I still don't think the autogenerated help should be exposed to people who are unfamiliar with the API. The wiki version has plenty of examples, and the sandbox lets you experiment, so both are vastly better.

Jdforrester-WMF added a subscriber: Jdforrester-WMF.

As a quick bodge we could change api-help-parameters from "Parameters:" to "Local parameters:" and sling a message like "Other parameters may be inherited."?

Perhaps that's good enough indeed! And I might propose a patch specifically for the description of this wbsearchentities action, just to clarify that uselang should be used there.

Change 636066 had a related patch set uploaded (by Jforrester; owner: Jforrester):
[mediawiki/core@master] API Help: Note that parameters may be inherited from other context

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

And I might propose a patch specifically for the description of this wbsearchentities action, just to clarify that uselang should be used there.

That'd be great, please do.

Change 636356 had a related patch set uploaded (by Pintoch; owner: Pintoch):
[mediawiki/extensions/Wikibase@master] Make wbsearchentities API help more explicit about language settings.

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