-announce
Maybe we should have a reply-to for api-announce mailings that prevent accidental chatter?
On Thu, Jun 4, 2015 at 12:45 PM, Brian Gerstle bgerstle@wikimedia.org wrote:
On Wed, Jun 3, 2015 at 1: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.
While it is (a little bit) nicer for new developers, they'll just burned (along with all the other current API users) when you change the defaults. What I'm trying to say is, changing the default seems like more work for more people with very little benefit. This is why https://developer.github.com/v3/ people https://www.reddit.com/dev/api version https://stripe.com/docs/api#charge_object APIs https://developer.linkedin.com/docs/rest-api.
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.
That's my point, why *ever* make it a breaking change? It's such a low cost to add a few characters to the URL to specify an API version. Our docs should tell developers what the current version is.
-- Brad Jorsch (Anomie) Software Engineer Wikimedia Foundation _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
-- EN Wikipedia user page: https://en.wikipedia.org/wiki/User:Brian.gerstle IRC: bgerstle