Hi Yuri,

I would rather be in favor of a global version number for the API, but with a few modifications.

All version numbers should be kept in a single file, independently of the modules.
The information in it is structured : a version number (which is used only by clients), a version tag (which is used by modules to decide how to reply), a description, ...
It allows module writers to be relatively independent to changes in other modules happening at the same time : the only thing to do is to fix the version number in this single file when merging.

Add a module to query the list of breaking changes in the API.

Nico



On Fri, Dec 21, 2012 at 1:02 AM, Yuri Astrakhan <yuriastrakhan@gmail.com> wrote:
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 :)

_______________________________________________
Mediawiki-api mailing list
Mediawiki-api@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-api