Make formatversion=2 more discoverable for new users
Open, Needs TriagePublic

Description

We want new developers to use formatversion=2 by default, it provides a cleaner output and requires less weirdness to work around (e.g. indexpageids=).

@Anomie suggested putting a notice/warning at the top of the *fm pages if not using formatversion=2.

Legoktm created this task.Jan 5 2016, 5:35 AM
Legoktm updated the task description. (Show Details)
Legoktm raised the priority of this task from to Needs Triage.
Legoktm added a project: MediaWiki-API.
Legoktm added subscribers: Legoktm, Anomie.
Restricted Application added subscribers: StudiesWorld, Aklapper. · View Herald TranscriptJan 5 2016, 5:35 AM
jayvdb added a subscriber: jayvdb.Jan 5 2016, 6:28 AM

If this is being considered for normal API requests/responses, I suspect that a notice/warning at the top of the *fm pages if not using formatversion=2 would be mostly preaching to the (lazy / easily annoy-able) converted who know what they are doing. Please at least put it at the bottom of the page; not at the top, which pushes the desired information down further.

However if it is only for the front page of the API, or action=help and similar: no worries, and include a "switch to version 2" link.

TTO added a subscriber: TTO.Jan 5 2016, 6:37 AM

Perhaps the API examples should use formatversion=2 (in docs and the API help itself).

Anomie moved this task from Unsorted to Needs Code on the MediaWiki-API board.Jan 5 2016, 8:33 PM
Anomie added a comment.Jan 5 2016, 8:36 PM

@Anomie suggested putting a notice/warning at the top of the *fm pages if not using formatversion=2.

More specifically, adding an additional i18n message just under 'api-format-prettyprint-header' for the applicable formats.

Perhaps the API examples should use formatversion=2 (in docs and the API help itself).

Yes, that would be a good idea too.

Tgr added a subscriber: Tgr.Dec 23 2017, 10:45 PM

People getting confused by query.pages not being an array is one of the more frequent problems on Stackoverflow. It would certainly be nice to improve this.