I would like to get some feedback on how best to proceed with the future API versions. There will be breaking changes and desires to cleanup, optimize, obsolete things, so we should start thinking about it. I see two general approaches I would really like to hear your thoughts on -- a global API version versus each module having its own version. Both seem to have some pros and cons.
== Per API ==
A global version=42 parameter will be included in all calls to API, specifying what functionality client is expecting. The number would increase every so often, like once a month to signify "API changes bucket". Every module will have this type of code when processing input parameters and generating reply:
// For this module: breakingChangeAversion = 15 breakingChangeBversion = 38 ... if requestVersion < breakingChangeAversion reply as originally implemented else if requestVersion < breakingChangeBversion reply as after breaking change A else reply as after breaking change B
PROS: simple, allows the whole API to introduce global breaking changes like new error reporting. CONS: every module writer has to check the current number at the API website before hard-coding a specific number into their module. There might also some synchronicity issues between module authors - making a change within a short time but long enough for a client writer to hard code the number while only knowing about one's changes. and assuming no changes to other modules.
== Per module ==
Each module name is followed by "_###" string. API ? action=Query_2 & titles=... Modules stay independent, each client knows just the modules it needs with their versions.
PROS: keeps things clean and separate. Each version is increased only by individual module writer due to a breaking change. CONS: it becomes impossible to make a breaking change in the "core" of the API, like maybe global parameters, a different system of error reporting, etc. I am not sure we have any of this, but...?
At the moment, I am still leaning towards the per-module approach as it seems cleaner.
For the version number itself, I think a simple integer would suffice - client specifies which interface version it wants, server responds in that format or returns an error. A complex 2.42.0.15 is not needed here - the client will know at the time of writing what version it supports. If the server can't reply with that request, it will fail. Knowing sub-numbers wouldn't help, but only complicate things.
Lets hope this will be a short and constructive thread of good new ideas :)