Mediawiki API documentation shortcomings
Open, LowPublic

Description

The current Mediawiki API documentation is on the terse side, and occasionally on the outdated one, as well. I'll name a few particular examples I have run across while writing a tool on Tool Labs recently, but it needs love throughout.

Examples:

  1. The use of continue, essential for most useful query actions, is not introduced on the main page, nor mentioned in the tutorial page. This is particularly painful considering the continue behavior has changed not so long ago, and some API client libraries have not updated yet, leading tool developers (like yours truly) to look for documentation to patch their clients.
  2. speaking of client libraries, there is no prominent link on the main page to the various clients available, other than at the (very bottom of) TOC box on the right. I think it is a safe bet that most people consulting that page would be delighted to use an existing client rather than roll their own raw API calls, so perhaps some mention of and link to the clients should be made earlier and/or more prominently.
  3. many API pieces, particularly props and lists, have very scanty examples, making it difficult to determine common usage or, conversely, nonsensical parameter combinations. For instance (this happened to me last week), it was not readily apparent how to obtain a thumbnail url from the API, and the imageinfo documentation does its best to hide the answer among dozens of parameters. It would have been great to have it clearly spell out that specifying a combination of an iiprop including url and providing a desired iiurlwidth would do the trick.

Thanks in advance!

Ijon created this task.Jan 21 2015, 6:00 AM
Ijon updated the task description. (Show Details)
Ijon raised the priority of this task from to Needs Triage.
Ijon added a project: Documentation.
Ijon added a subscriber: Ijon.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJan 21 2015, 6:00 AM
matmarex set Security to None.

It's a wiki, feel free to edit it :)

Ijon added a comment.Jan 21 2015, 7:13 AM

I do realize it's a wiki, of course. I opened this bug at S's explicit invitation, to call out an area needing attention. I'm afraid I'm not personally motivated to spend time systematically fixing this; I spend my volunteer energy elsewhere on the wikis.

Spage added a comment.EditedJan 24 2015, 1:18 AM

Thanks.
Re: 3, I updated imageinfo API doc mentioning the returned thumburl|width|height info and adding an example. Legoktm, Matmarex I kept the result as JSON (most API examples show XML output) and omitted the temporary continuation query warning.

I'll leave this open for 1 and 2.

Anomie added a subscriber: Anomie.Jan 24 2015, 1:40 AM

(most API examples show XML output)

That should probably be changed. The "canonical" output format is now json, but I'm working on changing it to a somewhat-different json.

Anomie moved this task from Unsorted to Non-Code on the MediaWiki-API board.Feb 19 2015, 6:05 PM
Aklapper triaged this task as Low priority.Mar 23 2015, 8:56 PM