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