Before playing around with api serious bugs should be fixed... I see xxXx unresolved bugs
on pahricator. It is frustrating....
Date: Thu, 18 Jun 2015 14:56:25 -0700
From: spage(a)wikimedia.org
To: wikitech-l(a)lists.wikimedia.org
Subject: Re: [Wikitech-l] API BREAKING CHANGE: Default continuation mode for action=query
will change at the end of this month
On Thu, Jun 18, 2015 at 9:26 AM, Brian Gerstle <bgerstle(a)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,
--
=S Page WMF Tech writer
_______________________________________________
Wikitech-l mailing list
Wikitech-l(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l