On Wed, Jun 3, 2015 at 10:04 AM, Brian Gerstle bgerstle@wikimedia.org wrote:
My question is: why does the default behavior need to change? Wouldn't continuing with the default behavior allow people to continue using the "rawcontinue" behavior for as long as we want to support it—without making any changes?
The decision to change the default came out of the same concerns that led to the improved action=help output and some of the other work I've been doing lately: We want to lower the barriers for using our API, which means that the default shouldn't be something user-hostile.
The raw continuation is deceptively simple: it looks straightforward, but if you're using it with a generator, multiple prop modules, and meta or list modules, your client code has to know when to ignore the returned continuation for the generator, when to remove a module from prop and then when to re-add it, and when to remove the meta or list modules. I wouldn't be that surprised to learn that more people have it wrong than correct if their code supports using prop modules with generators.
The new continuation actually is simple: you send the equivalent of array_merge( $originalParams, $continueParams ) and it just works.
Yes, some of the same could be said for making format=json&formatversion=2 the default. In this case the formatversion=1 output is just annoying rather than actually hostile (although representing boolean true as a falsey string comes close), so at this time there's no plan to make that breaking change.
I would like to point out that it might be a good idea add &formatversion=1 for anyone who wants to lock the current formatting in place.
On Wed, Jun 3, 2015 at 8:13 PM, Brad Jorsch (Anomie) bjorsch@wikimedia.org wrote:
On Wed, Jun 3, 2015 at 10:04 AM, Brian Gerstle bgerstle@wikimedia.org wrote:
My question is: why does the default behavior need to change? Wouldn't continuing with the default behavior allow people to continue using the "rawcontinue" behavior for as long as we want to support it—without making any changes?
The decision to change the default came out of the same concerns that led to the improved action=help output and some of the other work I've been doing lately: We want to lower the barriers for using our API, which means that the default shouldn't be something user-hostile.
The raw continuation is deceptively simple: it looks straightforward, but if you're using it with a generator, multiple prop modules, and meta or list modules, your client code has to know when to ignore the returned continuation for the generator, when to remove a module from prop and then when to re-add it, and when to remove the meta or list modules. I wouldn't be that surprised to learn that more people have it wrong than correct if their code supports using prop modules with generators.
The new continuation actually is simple: you send the equivalent of array_merge( $originalParams, $continueParams ) and it just works.
Yes, some of the same could be said for making format=json&formatversion=2 the default. In this case the formatversion=1 output is just annoying rather than actually hostile (although representing boolean true as a falsey string comes close), so at this time there's no plan to make that breaking change.
-- Brad Jorsch (Anomie) Software Engineer Wikimedia Foundation
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
mediawiki-api@lists.wikimedia.org