Last modified: 2014-10-07 15:41:21 UTC

Wikimedia Bugzilla is closed!

Wikimedia has migrated from Bugzilla to Phabricator. Bug reports should be created and updated in Wikimedia Phabricator instead. Please create an account in Phabricator and add your Bugzilla email address to it.
Wikimedia Bugzilla is read-only. If you try to edit or create any bug report in Bugzilla you will be shown an intentional error message.
In order to access the Phabricator task corresponding to a Bugzilla report, just remove "static-" from its URL.
You could still run searches in Bugzilla or access your list of votes but bug reports will obviously not be up-to-date in Bugzilla.
Bug 39592 - Version the API
Version the API
Status: NEW
Product: MediaWiki
Classification: Unclassified
API (Other open bugs)
All All
: Low enhancement (vote)
: ---
Assigned To: Nobody - You can work on this!
Depends on:
Blocks: api-2.0
  Show dependency treegraph
Reported: 2012-08-23 20:33 UTC by Jon
Modified: 2014-10-07 15:41 UTC (History)
17 users (show)

See Also:
Web browser: ---
Mobile Platform: ---
Assignee Huggle Beta Tester: ---


Description Jon 2012-08-23 20:33:40 UTC
During my short time of working with the mediawiki api I have come up against what I see as issues/bugs.

When I have asked that we rectify I have frequently encountered the response "we can't change this as that might break backwards compatibility"

I therefore think a versioning mechanism for the api would allow us to make these big changes without fear of disrupting existing users of the api.

This could be done via a query string parameter or separate url
{insert naming scheme here}
Comment 1 Sam Reed (reedy) 2012-08-23 21:19:04 UTC
If you've got a way to have all the changes without either a load of duplicate classes, or classes with tonnes of version related hacks/conditionals...
Comment 2 Krinkle 2012-08-24 15:30:33 UTC

That is the most future-compatible and easiest to implement.

In the future (perhaps a future rewritten API 2.0) it could be more like this (inspired by BrowserStack's JSON API)

https://localhost/w/api/1/[action][/primary parameter | query string]

more about that at bug 38891.
Comment 3 Jon 2012-08-24 16:10:15 UTC
+1 to Krinkle's suggestion.
It does seem like the simplest solution to moving the api forward.
Comment 4 Yuri Astrakhan 2012-12-26 18:51:36 UTC
I have began experimenting with the API versioning (sorry for my 6+ year absence). There is now a mediawiki-api labs at - I will post all API versioning development there for everyone to test their client code and extensions. Contact me if you want to join the project.

Current goal is to have a per module versioning scheme (this is required due to the modular api nature).


action=query will default to action=query1 - the original implementation, but will give a warning.

api.php help will show the latest version info

action=paraminfo will handle all versions

among things that will also be added is a structured warning system, e.g.

'warnings': {
  'main': {
    'usertext': 'Unrecognized parameters: param1,param2. Obsolete params: param3. The latest module version is 3.'
    'unknownparams': ['param1','param2'],
    'obsoleteparams': ['param3'],
    'newestversion': 3,
Comment 5 Yuri Astrakhan 2012-12-28 10:49:06 UTC
The first alpha version of the api versioning has been implemented. Grab it while it's hot.  All details in the email at
Comment 6 Yuri Astrakhan 2013-01-09 08:09:06 UTC
Update: The currently proposed API changes are at

Feel free to add ideas or discuss on the talk page
Comment 7 db [inactive,noenotif] 2013-01-16 19:10:18 UTC
Another idea for versioning is

image vs. file

The renaming of modules and output parameter was not done for backward compatibility, but with a new version this is may possible.

Other things like spelling issues can also be find in api.
Comment 8 Yuri Astrakhan 2013-01-16 19:16:53 UTC
db, please post your proposal in details at the

Renaming image to file sounds good, could you list all spelling mistakes you found on that page too?

Comment 9 Quim Gil 2013-05-02 22:37:31 UTC
Just a note to say that Aayush Sharma has submitted a GSoC proposal related to this report:
Comment 10 Quim Gil 2014-05-06 16:35:39 UTC
A year later... 

Yuri, this report is assigned to you. Are you working or planning to work on this?

CCing Moyz and Sumana, since this might be related to
Comment 11 Andre Klapper 2014-06-10 11:38:54 UTC
Yuri Astrakhan: You assigned this ticket to yourself in 2012. 
Could you please provide a status update and inform us whether you are still working (or still plan to work) on this issue? 
Only in case you do not plan to work on this issue anymore, should the assignee be set back to default and the bug status changed from ASSIGNED to NEW/UNCONFIRMED? Thanks.
Comment 12 Andre Klapper 2014-06-16 12:29:56 UTC
Yuri Astrakhan: I am resetting the assignee of this issue to default because there has been no progress in the last months. Feel free to take it again when you are actually planning to fix this. Thanks.
Comment 13 Yuri Astrakhan 2014-06-16 16:46:58 UTC
Yes, thanks, not working on it ATM.
Comment 14 Brad Jorsch 2014-09-24 14:11:11 UTC
(In reply to Sam Reed (reedy) from comment #1)
> If you've got a way to have all the changes without either a load of
> duplicate classes, or classes with tonnes of version related
> hacks/conditionals...

This is one big problem with the proposal, IMO.

And it can easily lead to code rot unless we first add unit tests for everything (which we *should* do, and probably will someday in our copious free time).

Another issue with versioning is that it promises that the old code using the old versions will continue to work, but a fair number of our breaking changes actually come from changes deeper in MediaWiki where we can't easily keep the old way working (or else we would have).

(In reply to Krinkle from comment #2)
> Proposing:
> https://localhost/w/api.php&version=1&action=..&....
> That is the most future-compatible and easiest to implement.

A single "version" parameter doesn't work well at all when you remember that we have API modules coming in from extensions all over the place.

Even a version per module can sometimes be problematic: if two unrelated breaking changes are made to the module, one arbitrarily gets "v3" and one gets "v4", but a client needing BC behavior for v3 but new behavior for v4 is stuck.

I think feature flags to select new behavior and a good deprecation process will take care of most things that actually need improvement, to the point where we can do per-module versioning on an ad hoc basis rather than trying to force it everywhere.

Note You need to log in before you can comment on or make changes to this bug.