Aryeh Gregor schreef:
On Wed, Aug 20, 2008 at 1:58 PM, Victor Vasiliev vasilvv@gmail.com wrote:
Yes, you just have to worry that query.php is replaced with api.php, which may be then replaced with something else. And also, I went through the mediawiki-api archives and found about 9 breaking changes for API. Pretty stable, isn't it? :)
I don't understand why there are ever breaking changes in the API. THE API SHOULD NEVER EVER EVER CHANGE. IT SHOULD BE A STABLE INTERFACE. There needs to be a policy, set in stone, not negotiable, that behavior for a given API query should NEVER change in an incompatible fashion. If something is inconsistent it should be deprecated and a new function instituted to replace it. The old deprecated way could then be marked for a few years (say, three years, or at least one year) before finally being removed. Authors of bot frameworks should be encouraged to write code checking for <deprecated> or whatever and having their framework raise a warning of some kind to inform them that they should update it.
This really seems like a no-brainer to me. But, I'm not an API developer, so . . .
Those 9 breaking changes sound far worse than they are. Most breaking changes are allowed as such because they *technically* change the API's behavior, but in a way that's unlikely to bother people who use decent frameworks. Anyway, here they are:
[1] was done on the request of an end user and to achieve consistency across modules. As I pointed out to that user, I doubted that anyone actually *used* the old behavior, or would even notice when it was changed. [2] was done to prevent blowing up databases with LIMITless queries. The limit/continue interface has existed for other modules for ages, and supporting it for additional modules on the client side should be trivial. [3] broke something 24 hours after introducing it and made it actually do something useful [4] was announced by Yuri 10 months before hybrid support (i.e. support for both the old and the new parameter) was finally abandoned [5] and [6] handle erroneous parameters more gracefully, which was a much-requested improvement but technically broke BC, because erroneous requests would return a warning rather than an error [7] was, again, a few days old feature that was moved to a separate module. Anyone quick enough to support such a young feature can change one word in the module call equally quickly [8] was another change to a new module that prevented invalid XML from getting output [9] was partially undone in [8] (the userinfo part); the other part was more database-blowup avoidance
Breaking changes got a bad name earlier because one of them made it kind of impossible to support both the old and the new behavior at the same time. This had already been fixed, but the incompatible behavior was sadly present in 1.12.0rc1 (fixed in the final 1.12.0 release, though), and now that I know of the issue, I'll think about supporting both old and new behavior at the same time in future breaking changes. Ironically, [5] made that kind of support possible in certain situations.
Roan Kattouw (Catrope)
[1] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-August/000660.html [2] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-July/000588.html [3] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-June/000576.html [4] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-May/000528.html [5] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-May/000541.html [6] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-May/000543.html [7] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-January/000319.html [8] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-January/000311.html [9] http://lists.wikimedia.org/pipermail/mediawiki-api/2008-January/000310.html