Requests for comment/API roadmap/Versioning discussion

Per-module versioning
api.php ? action=query~2 & ... Each API module will have its own versioning number. This approach provides independence between different components, and solves the version conflict problem described in the other section.

Global Version Number
api2.php ? action=query & ...

One global version is good to deal with overall compatibility issues, such as changing the result data format: structured warnings, json only format, etc.

Despite this, even though having one main version parameter approach seems more reasonable at a first glance, it seems to be a dead end with respect to the modular expandable nature of our API. Any extension can add an API module, but no one can ever guarantee that an extension will be upgraded at the same time as the core.

Let's say there is a server with the core ver 1102 and an extension ver 1206. Later MW 1309 is released, with the new API behavior. Independently an extension 1309 is also released to support the new features.

On the server, admins update the core right away, but decide to delay extension deployment because they might want to do additional testing, or for any other reason. So now the core 1309 is working with extension 1206. This is totally fine so far - the core frequently runs with the older extensions.

After MW update, but before extension is put in production (which could be a long time), API client is created against the API version 1309. The developers use one global version number to access API - 1309 - to test and develop the new program, and they assume that the extension results will stay the same - they might not know that the new extension is pending. But later, at a whim of an admin, the extension is finally added to production, at which point the client fails - what was suppose to be a firm contract - "you ask for ver X you get ver X despite upgrades" has been broken.

To avoid any kind of surprises like this, there should never be any "default" fallback behavior in the API. The developer may query which versions are available, and choose to work with the one available, but will do so explicitly. See Defaults section below.