On Thu, Jun 18, 2015 at 9:26 AM, Brian Gerstle bgerstle@wikimedia.org wrote:
I guess it comes down to is this: if we're going to continue supporting old behavior, they should be accessible via the same old requests. *This removes the need for existing clients to be updated in the first place*. If we eventually want to delete the old code keeping the old behavior separated from the new will make it clear & explicit what's being dropped and what to use instead. ...
Lastly, changing the default behavior to make things sane for new developers is, IMO, a bad trade-off
That seems the crux of it. Because the MediaWiki API isn't versioned (and there are good reasons for it), the recommended "best practices" form of an API request evolves, something like
api.php?continue=& formatversion=2 &utf8= &*your_actual_params*
and over time the best practices boilerplate at the front gets longer unless we change a default and break old clients. Examples and documentation should show best practices; T103015 is to use formatversion=2 and "https" in all example API requests. (We should have used &continue= in examples for the last year, it's too late now.)
The above is actually a real URL and shows three different approaches: 1. As the e-mail subject says we're going to make continue= the default in a few weeks so you won't need to add it (but clients MUST add rawcontinue= to get the old behavior). 2. formatversion=2 is the future but won't be the default for a while. 3. If you request formatversion=2 then results default to utf8, so you don't need to specify utf8. (Note formatversion=2 only applies to format=json or php.)
Which approach to take is a judgement call, I'm interject-opinion-reluctant :)
because they'll eventually get tripped by us pulling the rug out from under their feet by *breaking backwards compatibility stable APIs*.
Or, over time the best practices boilerplate endlessly expands: responselayout=clean &reporterrors=schema &facebookoverlordmode= ... Does that make our API "user-hostile"? IMO it just makes it wordy.
Those sorts of changes should be reserved for experimental or even beta APIs. Continuing queries seems like a stable—and pervasive—part of the API.
Cheers,