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...

Proposing:
https://localhost/w/api.php&version=1&action=..&....

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.

+1 to Krinkle's suggestion.
It does seem like the simplest solution to moving the api forward.

I have began experimenting with the API versioning (sorry for my 6+ year absence). There is now a mediawiki-api labs at https://labsconsole.wikimedia.org/wiki/Nova_Resource:Mediawiki-api - 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).

/w/api.php?action=query2&...

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,
}

}

The first alpha version of the api versioning has been implemented. Grab it while it's hot. All details in the email at http://lists.wikimedia.org/pipermail/mediawiki-api/2012-December/002811.html

Update: The currently proposed API changes are at http://www.mediawiki.org/wiki/Requests_for_comment/API_Future

Feel free to add ideas or discuss on the talk page

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.

db, please post your proposal in details at the
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future

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

thx!

Just a note to say that Aayush Sharma has submitted a GSoC proposal related to this report: https://www.mediawiki.org/wiki/User:Aayush251/gsoc

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 https://www.mediawiki.org/wiki/Data_%26_Developer_Hub

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.

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.

Yes, thanks, not working on it ATM.

(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.

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.

Isn't that how versions are supposed to work?

Agreed. I'd really like to see this reopened. This is yet another reason RESTBase is so attractive.

Another issue with versioning is that it promises that the old code using the old versions will continue to work

Does it really, necessarily? Should old APIs not be deprecated?

In T41592#1907325, @Jdlrobson wrote:

Agreed. I'd really like to see this reopened. This is yet another reason RESTBase is so attractive.

So far, versioning of RESTBase endpoints is only theoretical. The entire current RESTBase api offering is sitting under /api/rest_v1/ in the Wikimedia servers' namespace and all endpoints are marked as either "unstable" or "experimental". I'm not trying to say that there hasn't been some thought put into how handling multiple concurrent versions of a RESTBase provided API may work, but the benefits of that to actual consumer code versus the costs of maintaining older versions have yet to be proven.

Please provide practical examples of where versioning would have been useful in past breaking changes.

Here's a quick look at the most recent mediawiki-api-announce emails:

• DEPRECATION: Removal of lgtoken, cookieprefix, and sessionid response values from action=login - API change that is prompted because of changes in underlying MediaWiki related code, given that the rest of MW doesn't want clients to manually set cookies, it's not something we would want to continue supporting
• BREAKING CHANGE: Removal of deprecated formats dbg, txt, and yaml - Removed because we don't want to support these
• Tips for using bots and user scripts with Flow - versioning wouldn't help at all, because the underlying pages are changing
• Wikimedia wikis version format changing in 1.27 releases - Again, another internal MW/Wikimedia change that the API wouldn't have been able to provide back-compat for
• Wikidata API breaking changes - mostly format changes because the original implementation of XML support was hacky and improper, could've been versioned and there is precedent for versioning format changes.
• Deprecation of generatexml parameter to action=parse, prop=revisions, and prop=deletedrevisions - parameter rename, could be versioned. Current strategy is to wait until usage of the deprecated parameter drops to a significant point
• BREAKING CHANGE: Removal for wddx and dump output formats (and reminder of future removal of yaml, txt, and dbg formats) - see above
• Wikidata - Deprecation & Removal of the ungroupedlist API parameter - removed due to code complexity and low usage, versioning wouldn't help since they didn't want to maintain that code

In T41592#1907353, @Sigma wrote:

Another issue with versioning is that it promises that the old code using the old versions will continue to work

Does it really, necessarily? Should old APIs not be deprecated?

That's not what Anomie meant, the rest of the sentence said:

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).

And there are other changes like [1] or [2] where keeping back-compat would be impossible.