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 :)
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.comwrote:
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
Nicolas, I'm not sure I understood - could you give a sample of this file? What kind of tags and how will they be used? Btw, keep in mind that many modules could be added at runtime by third party developers, for example as part of their mw extension, and might not be in the main source tree.
Thanks!!!
Hi again,
By tag, I meant something expressive that modules should use instead of a raw version number. Something like the "breakingChangeAVersion" constant in your example.
I'm not expert in PHP, so I don't know how you would do this. Maybe an array of objects, each object having a version number, a name, a description, ... Each module would check where the given version number is relatively to the breaking change it is concerned with.
Not sure I'm very clear...
Nico
On Fri, Dec 21, 2012 at 8:38 AM, Yuri Astrakhan yuriastrakhan@gmail.comwrote:
Nicolas, I'm not sure I understood - could you give a sample of this file? What kind of tags and how will they be used? Btw, keep in mind that many modules could be added at runtime by third party developers, for example as part of their mw extension, and might not be in the main source tree.
Thanks!!!
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Nico, unfortunately, tags can make sense only within the context of a specific module, i.e. featureA got introduced into moduleX. Because module development is entirely bazaar style, it would be very hard to keep one central repository of tags for the thirds party modules. I like one version to rule them all, but don't think we can be as flexible with it.
Brad, I agree with the overall drawbacks of having a version system, but the only alternative is to have a converting layer on top of the regular API that will change things on the fly if the request had a different version number. This would solve the hypothetical security issue - only one API to check, but will more likely cause stability problems - it is much easier to mess up in the additional layer than in the specific module that understands the change.
On Sat, Dec 22, 2012 at 8:54 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Brad, I agree with the overall drawbacks of having a version system, but the only alternative is to have a converting layer on top of the regular API that will change things on the fly if the request had a different version number. This would solve the hypothetical security issue - only one API to check, but will more likely cause stability problems - it is much easier to mess up in the additional layer than in the specific module that understands the change.
Please do expand on the list of pros.
Versioning pros
* Allows clients to avoid updating when the API changes. * Reduces the cost of making a breaking change * Organize feature changes - if the client asks for ver X, API guarantees the capabilities of X and result in format X. * Recommended API usage is shown as the latest version. If API decides to change default behavior into optional, new developers will use the recommended way from the start. * No clutter with ever expanding list of additional parameters - with ver, new parameters could replace old ones, or change their meaning, or be removed completely without breaking any clients. * Ability to obsolete capabilities in a structured way: MW supports API requests with version X+, but will give standard warning for anything below version Y. No need to parse warning messages to see if specific feature change applies.
On Sat, Dec 22, 2012 at 9:13 AM, Brad Jorsch bjorsch@wikimedia.org wrote:
On Sat, Dec 22, 2012 at 8:54 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Brad, I agree with the overall drawbacks of having a version system, but the only alternative is to have a converting layer on top of the regular
API
that will change things on the fly if the request had a different version number. This would solve the hypothetical security issue - only one API
to
check, but will more likely cause stability problems - it is much easier
to
mess up in the additional layer than in the specific module that
understands
the change.
Please do expand on the list of pros.
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Pros of any versioning scheme:
- Allows clients to avoid updating when the API changes. - Reduces the cost of making breaking changes.
Cons of any versioning scheme:
- Requires the code to accumulate more and more "if version < foo" cases, which must be tested, reviewed for security, and updated as things in core change. - Can't entirely prevent breaking things. For example, the introduction of ContentHandler removed sectioning for Javascript and CSS pages, and there's no sane way to preserve that in an old API version.
Please expand these lists.
On Thu, Dec 20, 2012 at 7:02 PM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
== 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".
Why wouldn't the version of Mediawiki (e.g 1.20.1) work as the "version" of the API? It is true that non-core modules would have to synchronize their releases with versions of Mediawiki, but that seems like a small cost. For most people, the time they will see API breaking changes is when they upgrade to a new version of Mediawiki.
If the version number need to be tied to the month, it would make more sense to make that explicit, e.g. versions "201301", "201302", etc., so there is a more clear link between the version number and the date that it took effect.
- Carl
Why wouldn't the version of Mediawiki (e.g 1.20.1) work as the "version" of the API? It is true that non-core modules would have to synchronize their releases with versions of Mediawiki, but that seems like a small cost. For most people, the time they will see API breaking changes is when they upgrade to a new version of Mediawiki.
I agree about year-month notation, but because extensions developers do not know when their code will be added to production, think of this scenario (very likely IMHO):
A server starts with the Mediawiki ver 201102 and an extension ver 201206 Later MW 201309 is released, with the new API behavior. Independently an extension 201309 is also released to support new features.
On the server, admins update the core MW right away, but decide to delay extension deployment because they might want to do additional testing, or for any other reason. So now you have MW 201309 and the extension 201206. Which could be totally ok - MW frequently runs 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 201309. The developers testing the system assume, incorrectly, 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 A you get ver A despite upgrades" has been broken.
From the looks of it, since API is based on plugins like this, we can't
really keep extensions in sync - simply because developers do NOT know when it will be placed into production.
mediawiki-api@lists.wikimedia.org