API versionning strategy - Mediawiki-api

21 Dec 2012

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 :)