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.
 * I disagree that an overal version would cause a conflict. It depends to what degree you allow a module to customize its output format. If this is kept central then the format is decided by mediawiki core. Thus, updating core will upgrade the format across all modules. If core introduces a new formatting feature and the extension uses it, but the site is running an older version of mediawiki core than the extension, then the module will be disabled. Just like we do already for MediaWiki extensions (except that due to the absence of a proper version detection for extensions instead the wiki goes down entirely due to an uncaught exception somewhere, we should make it more graceful than that). And similarly if a formatting feature was removed from core, and the extension still uses it, it just gracefully fails.
 * Or even better, we should go for best practice all the way and keep major versions around and have extensions register their modules to the version directly (e.g. extensions/FooBar/api/2/ApiFooBar.php). So that versions always blend together with whatever is available. This assumes that we don't remove or add things in minor releases and maintain major releases.
 * Even if we don't implement multi-versions in core, we shouldn't give this all up just for the edge case of sites that incorrectly maintain their website. They should update core and extensions simultaneously (and I don't mean right after one another, but really simultaneously. Set up the next version with the next version of the extensions, point to the same config and then switch over). This may seem advanced, but I don't think we should compromise all of that just for some less-experienced site admins that don't know how to manage their site.
 * Actually, if we go with multi-version (which GitHub and BrowserStack also do) we wouldn't have to compromise on anything and it would even work properly with different core/extension versions for those site admins that update core and extensions separately. Krinkle (talk) 23:48, 27 January 2013 (UTC)