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