Sorry, guess I'm also calling #1 into question, since the old behavior should have already been the default or selectable by its own flag/parameter/URL-path-component/content-type/whatever.
On Thu, Jun 4, 2015 at 2:08 PM, Brian Gerstle bgerstle@wikimedia.org wrote:
Just found the deprecation process document https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap, specifically:
- If not already present, a request parameter will be added to
specifically request the old behavior. 2. The change will be announced: - A message will be sent to the mediawiki-api-announce http://lists.wikimedia.org/pipermail/mediawiki-api-announce/ mailing list. - Deprecation warnings will be output when neither the select-new-version nor the select-old-version flags are used. Logs will also be made. 3. *After a suitable timeframe, the new version will become the default.* 4. *Any flag to select the new version explicitly may at some point be removed, leading to "unrecognized parameter" warnings.*
My argument is that step #3 is unnecessary and #4 needs clarification in that IMO APIs should only be removed when they are no longer supported, otherwise you're just creating busy work for yourself and the clients.
On Thu, Jun 4, 2015 at 1:59 PM, Brian Gerstle bgerstle@wikimedia.org wrote:
I know about the phab ticket, but I'm glad you referenced it because I found this:
(Anomie): I think feature flags to *select new behavior* and *a good
deprecation process* will take care of most things that actually need improvement, to the point where we can do per-module versioning on an ad hoc basis rather than trying to force it everywhere.
IOW, why don't we continue w/ this feature flagging approach, which seems like a decent way to version APIs and prevent breaking backwards compatibility?
On Thu, Jun 4, 2015 at 1:05 PM, Legoktm legoktm.wikipedia@gmail.com wrote:
On 06/04/2015 09:45 AM, Brian Gerstle wrote:
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%3E
version https://stripe.com/docs/api#charge_object APIs https://developer.linkedin.com/docs/rest-api.
I'd recommend reading https://phabricator.wikimedia.org/T41592, which contains a pretty good rationale of why we currently don't version the API.
-- Legoktm
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
-- EN Wikipedia user page: https://en.wikipedia.org/wiki/User:Brian.gerstle IRC: bgerstle