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 <[email protected]>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 > [email protected] > https://lists.wikimedia.org/mailman/listinfo/mediawiki-api > >
_______________________________________________ Mediawiki-api mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
