Page MenuHomePhabricator

RFC: Define a policy for REST API result format versioning / negotiation
Closed, ResolvedPublic

Description

The REST API has been following an API versioning policy. This policy can be summarized as follows:

  • A global API version in the path,
  • stability markers on individual entry points, and
  • the guarantee that stable end points won't change in breaking ways.

Recently, we have found a need to make some significant changes in the HTML format returned by the /page/html entry point. While clients interested in view HTML typically won't notice a difference, other clients like VisualEditor will need to explicitly handle the new format.

This brings up the question of how to handle this kind of semi-breaking return value change in terms of API versioning. As with API versioning in general, our goal is to provide a stable interface that clients can rely on. At the same time, we want to be able to refine the API and return types.

In this case, incrementing the major API version number would be a fairly disruptive measure. If followed for all return value changes in stable end points, this would lead to a proliferation of basically identical major API versions. Clients would need to update a lot of URLs to use the latest API version. An alternative strategy for per-entry point return format changes seems to be needed.

We have two main questions related to this that we would like to ask you for your input on:

How to request a specific response format

In order to avoid breaking clients, we need them to specify the response format they are expecting. https://www.mediawiki.org/wiki/Talk:API_versioning describes two main alternative approaches to achieve this:

  1. A query parameter to request a specific format version.
  2. Use of the HTTP Accept header to request a specific mime type in the response.

We have always indicated the format version in the mime type: text/html; profile="mediawiki.org/specs/html/1.1.0, but aren't currently responding to Accept headers for format selection.

Discussion and decision

In the discussion on this task and last week's IRC meeting, there was a slight preference for using the Accept header over query strings for format negotiation. It was noted that support for query strings could be added additionally at a later point.

With the conclusion of the final comment period, the Architecture Committee decided in its meeting on 2016-02-24 to go with Accept headers.

What to do if no format was specified

While we want to at least strongly encourage all clients to specify the content type they are expecting, there might still be some clients or test requests that will not explicitly demand a specific version. A few response options for this case are:

  1. Announce new format versions as early as possible before deployment, and return the latest deployed format version when no explicit version was specified.
  2. Announce and delay changes to the default format version for 1-2 months.
  3. Do not allow requests without a specified format version. Return an error if no format version was supplied.

Discussion and decision

The main question in the discussion was whether strong encouragement will be enough to persuade clients to explicitly specify a format version. A common concern was that clients without explicit version in the request won't pay attention to announcements either, and will only find out when things break.

There was consensus for starting with strong encouragement and immediate default changes (option 1). If most clients continue to omit explicit versions in their requests & this leads to breakage, then we can reconsider enforcing explicit versions in the request (option 3).

With the conclusion of the final comment period, the Architecture Committee decided in its meeting on 2016-02-24 to start with option 1) (strong encouragement and quick default updates).

Related Objects

Event Timeline

GWicke raised the priority of this task from to Normal.
GWicke updated the task description. (Show Details)
GWicke added a subscriber: GWicke.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJan 21 2016, 10:58 PM
GWicke set Security to None.
GWicke edited subscribers, added: ssastry, cscott, Pchelolo and 5 others; removed: Aklapper.
GWicke updated the task description. (Show Details)Jan 21 2016, 11:07 PM
GWicke updated the task description. (Show Details)
GWicke updated the task description. (Show Details)
GWicke renamed this task from RFC: Refine the API versioning strategy for individual entry points to RFC: Define a policy for REST API result format versioning / negotiation .Jan 22 2016, 12:09 AM

This discussion is entering its final comment period:

https://lists.wikimedia.org/pipermail/mediawiki-api/2016-January/003701.html

Based on your input here, the Parsing, Editing and Services teams will make a decision next Wednesday, February 2nd.

for "Question 2: Which format to return by default", i think it's better to have some announcement before behavior is changed

Legoktm added a subscriber: Legoktm.Feb 8 2016, 6:28 AM

It's hard to give feedback without knowing the actual breaking change you plan on making. Breaking changes in the api.php API typically involve checking how many users are currently using the parameters, evaluations of some of the popular client libraries, and sometimes input on the mediawiki-api/wikitech-l lists, or even RfCs.

A query parameter to request a specific format version.

So requests would end up looking like https://en.wikipedia.org/api/rest_v1/page/title/Main%20Page?realversion=1.1? It seems silly to require the client to pass two version parameters...

Use of the HTTP Accept header to request a specific mime type in the response.

This seems like a pain for people trying to test stuff in their web browser, so I'd recommend not.

Overall, your suggestions lead me back onto why the api.php endpoint doesn't support versioning (T41592)...serving as a wrapper around individual modules, it doesn't really make sense to maintain an overall version, you really want versions for each individual module you're calling.

It also seems like this change is happening due to a Parsoid/VE change? Shouldn't we be changing a Parsoid version number then?

Return the latest format version by default, or

I think this is pretty clearly a non-starter, given there is no plan of announcement (the second option does though, so it seems intentional you didn't include it here??). If you do provide an announcement, I think it only works if you require every client to pass a version parameter, because if it isn't required, people won't include it, and then you'll end up breaking clients, which you don't want to.

announce changes to the default version 1-2 months in advance, then change the default format to the latest.

I mean, compared to option 1, this is the least bad option, but I think you'll quickly find that 1-2 months is either too quick (think how much notice we gave for the query-continue change and formatversion=2), or too slow (only one user is actually using the API, and once notified they fix their code in a few days, etc.), or just perfect depending on what the actual change is ;).

So basically...need more context. Anyways, sorry for the late response, was on vacation, etc.

Based on your input here, the Parsing, Editing and Services teams will make a decision next Wednesday, February 2nd.

Looks like no one else gave input here in time :( What was the decision?


On a process note, is this not a TechCom-RFC? If so, why not?

@Legoktm: quick comment. We'll be bumping the Parsoid HTML version number. This discussion is about what version of Parsoid HTML clients receive via the RESTBase API and how they can request specific / latest versions.

On a process note, is this not a ArchCom-RfC? If so, why not?

Initially we wanted to make progress on this more quickly, but then some other stuff got in the way & things aren't to rushed any more. So, I made this an ArchCom RFC. It is scheduled for the IRC office hour next Wednesday, and we'll make a decision at the following meeting.

GWicke updated the task description. (Show Details)Feb 12 2016, 12:17 AM
GWicke added a comment.EditedFeb 12 2016, 12:25 AM

I think it only works if you require every client to pass a version parameter, because if it isn't required, people won't include it, and then you'll end up breaking clients, which you don't want to.

I think there is broad agreement that we want to at least strongly encourage all clients to be explicit about the format they are expecting, and have tweaked the wording a bit to reflect this more strongly. I have also added the stronger option of requiring this as option 3) in the RFC.

My personal preference would be to go with strong encouragement first, and then see what the uptake is like. Other APIs like github's use similar "strongly encouraged" language, and I think there is an argument to be made for keeping the bar to entry low.

Meeting invite for the IRC meeting: E143: RFC Meeting: REST API result format versioning / negotiation (2016-02-17, #wikimedia-office)

If that meeting goes well, the RFC goes to last call at the conclusion of the meeting, and then would be approved 2016-02-24 (barring any showstopper objections in the interim).

GWicke updated the task description. (Show Details)Feb 17 2016, 5:58 PM
GWicke updated the task description. (Show Details)Feb 17 2016, 6:02 PM

Log from the IRC discussion on #wikimedia-office today:

[14:01] <gwicke> #startmeeting REST API response format version negotiation: https://phabricator.wikimedia.org/T124365
[14:01] <gwicke> hello
[14:01] <TimStarling> meetbot broken?
[14:01] * legoktm waves
[14:01] <gwicke> yeah, not sure it's around
[14:01] <Scott_WUaS> greetings All
[14:02] <gwicke> anybody knowledgeable about meetbot around?
[14:02] * gwicke looks at https://wikitech.wikimedia.org/wiki/Nova_Resource:Tools/Tools/meetbot
[14:03] <TimStarling> I'm doing it
[14:03] <gwicke> I don't have an account in tool labs
[14:03] <TimStarling> hmm, maybe not
[14:04] <TimStarling> maybe I don't have an account either, or the restricted bastion is not documented
[14:04] <mobrovac> tech problems - so typical for engineers :D
[14:04] <gwicke> well, worst case we can just pretend it's working and then grep everything with #info etc from our own logs
[14:04] <gwicke> let me give a short intro on the RFC
[14:05] <gwicke> #link https://phabricator.wikimedia.org/T124365
[14:05] <gwicke> the scope of this RFC is negotiating the response format of REST API end points
[14:05] <gwicke> the REST API has a global version (currently v1) that is used to version the API as a whole
[14:06] <gwicke> it will be incremented whenever the API layout or the request interface of stable end points is changed in incompatible ways
[14:06] <TimStarling> I have just been reading http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html
[14:06] <gwicke> the 'stable' in there refers to the per-entrypoint stability markers
[14:07] <gwicke> as described in https://www.mediawiki.org/wiki/API_versioning
[14:07] <TimStarling> and http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
[14:07] <gwicke> now, getting back to the RFC, we still have a need to sometimes change the response returned from a *stable* entry point in incompatible ways
[14:08] <gwicke> concretely, the Parsoid team is about to move data-mw (template metadata etc) from inline attributes to a separate JSON blob; this change would break existing clients if we don't provide a means to continue to receive the old response
[14:09] <mobrovac> if they don't want to switch to the new layout, that is
[14:09] <gwicke> the main questions in this context are: 1) How to request a specific response format, and 2) What to do if no format was specified
[14:10] <subbu> or if they cannot be switched to accept the new layout at the exact same moment the new format is dpeloyed.
[14:10] <gwicke> for 1), there are two "wrong" proposals, meaning that both have pros & cons
[14:10] <gwicke> https://www.mediawiki.org/wiki/Talk:API_versioning has a list of pros / cons for each
[14:11] <TimStarling> ah yes, I see it already links to that Troy Hunt article
[14:11] <gwicke> *nod*
[14:11] <TimStarling> his approach was to just do it all the ways
[14:12] <TimStarling> that way you have a URL if you need one for some reason, but normally you can use an Accept header
[14:12] <mobrovac> for 1) i'd be for the accept header
[14:12] <gwicke> the downside is that you get the complexity of both
[14:12] <mobrovac> looks much cleaner and is more API-like
[14:12] <gwicke> wrt VCL complexity and documentation
[14:13] <gwicke> but, the pro is that you can easily link to a specific version
[14:13] <gwicke> *and* link to the latest
[14:13] <mobrovac> right, but with query params you might get into the mw api query params caching trap we have right now
[14:14] <gwicke> yeah
[14:14] <mobrovac> wrt linking, the content render doesn't actually change
[14:14] <TimStarling> it's doable though, with a lot of logic in varnish
[14:15] <TimStarling> it's apparently more common to have the version in the path though
[14:15] <mobrovac> TimStarling: right, but it's less of an effort to do so with clean headers
[14:16] * mobrovac "it's doable" should be every engineer's moto :P
[14:16] <gwicke> global api versions are very common in the path, per-entrypoint versions a bit less so
[14:16] <DanielK_urlaub> what do the URIs identify? An API entry point, or the data returned by that entry point (or eve nthe thing described by the data returned by the entry point)?
[14:16] <DanielK_urlaub> in wikidata, we use separate URIs fpr the Thing and the data describing the Thing.
[14:16] <DanielK_urlaub> the first can't be versioned, the second one can
[14:17] <gwicke> it's typically slightly different representations of the same logical resource
[14:17] <subbu> DanielK_urlaub, example urls for 'the thing' and 'the data describing the thing'?
[14:17] <gwicke> so very much in the spirit of HTTP content negotiation
[14:18] <TimStarling> parsoid already has /v2
[14:18] <DanielK_urlaub> subbu: https://wikidata.org/entity/Q42 and https://www.wikidata.org/wiki/Special:EntityData/Q42.rdf
[14:18] <subbu> TimStarling, and /v3
[14:18] <gwicke> TimStarling: that's the global API version, which is a different issue
[14:18] <subbu> because the api uris completely changed.
[14:19] <DanielK_urlaub> subbu: ...and https://www.wikidata.org/wiki/Special:EntityData/Q42.rdf?revision=293317199
[14:19] <gwicke> DanielK_urlaub: how do you represent changes in your rdf format?
[14:19] <DanielK_urlaub> gwicke: my point is: if your api returns data that is itself versioned, you have multiple dimensions of versioning to deal with
[14:19] <gwicke> and how do you request a specific RDF format version?
[14:20] <DanielK_urlaub> you may have to encode both in the uri without creating confusion
[14:20] <TimStarling> ah right, /:domain/v3
[14:20] <TimStarling> it's not at the top level
[14:20] <subbu> DanielK_urlaub, so, clients making requests to Q42 have to specify the rdf version in the request?
[14:20] <SMalyshev> gwicke: there's https://www.wikidata.org/wiki/Special:EntityData/Q42.rdf?flavor=dump for example
[14:20] <DanielK_urlaub> gwicke: specific rdf version https://www.wikidata.org/wiki/Special:EntityData/Q42.rdf?revision=293317199
[14:21] <gwicke> DanielK_urlaub: revision as in MW revision is a different resource already
[14:21] <DanielK_urlaub> of course
[14:21] <TimStarling> (Article titles should be capitalized, which will prevent an article named 'v3' from being an additional source of ambiguity.)
[14:21] <subbu> i.e. a request to https://wikidata.org/entity/Q42 might return a new data object after the rdf is updated.
[14:21] <DanielK_urlaub> but if i use ?version?1234 in the uri, it's not obvious if that refers to the version of the resource, or the version of the api
[14:22] <gwicke> the core question is whether we should use Accept headers, a query parameter, or both
[14:22] <DanielK_urlaub> subbu: indeed it will. and if you resolve it, it actually redirects to the document URI (also without a fixed version, though)
[14:22] <Scott_WUaS> *nod*
[14:22] <mobrovac> so, to clarify, we are discussing here returning *the same revision* of the content, only slightly differently represented
[14:23] <gwicke> yes, the revision question is orthogonal / OT
[14:23] <DanielK_urlaub> gwicke: i guess my point is: if it's a query parameter, make the name very clear. apiversion=123, not just version=123
[14:23] <gwicke> DanielK_urlaub: makes sense
[14:24] <gwicke> the proposal presents a strawman of ?accept=text/html;profile=mediawiki.org/specs/html/1.0.0
[14:24] <DanielK_urlaub> yea, the revision thing is only relevant in as much we should avoid clashes and confusion when naming parameters
[14:24] <gwicke> #link https://www.mediawiki.org/wiki/Talk:API_versioning
[14:24] <DanielK_urlaub> gwicke: does the profile only govern the output representation, or also the interpretation of the input?
[14:25] <gwicke> it's the mime type of the response
[14:25] <gwicke> so only affects the response
[14:25] <DanielK_urlaub> so how would you version breaking changes to the parameters an api accepts?
[14:25] <gwicke> backwards-incompatible changes to the request part would force an increment of the major API version
[14:26] <gwicke> (or the creation of a new entry point, to avoid breakage)
[14:26] <TimStarling> so gwicke, your preferred solution is the Accept header?
[14:26] <DanielK_urlaub> and how does the client specify the major api version in a request?
[14:26] <mobrovac> DanielK_urlaub: it's part of the URI - /api/rest_v1/ ...
[14:27] <gwicke> TimStarling: if I have to pick one, I think I am leaning slightly towards the Accept header
[14:27] <mobrovac> +1
[14:27] <DanielK_urlaub> mobrovac: i thought that was only one of the alternatives, and not the one that gwicke is prefering
[14:27] <subbu> if I had to pick as a user of an API, uri query params for versioning would be simpler from a usability PoV, but understand it complicates aspects of the implementation .. and accept header feels cleaner.
[14:27] <mobrovac> fwiw, i think allowing both could create too much confusion
[14:28] <subbu> uri query params for per-endpoint format versioning, to be clear.
[14:28] <gwicke> one thing that's strong about Accept is the symmetric use of the content type
[14:28] <TimStarling> the Accept header would be forwarded to parsoid?
[14:28] <DanielK_urlaub> gwicke: i'm getting the idea that the accept header is good for specifying the expected output format, but versioning of the api input should go into the url.
[14:28] <mobrovac> DanielK_urlaub: the overall api version is contained in the url itself, but here the focus is on small mime-type-like changes in the returned content
[14:29] <mobrovac> subbu: why would it be simpler for you?
[14:29] <gwicke> TimStarling: potentially; there are optimizations we can apply if an older version of the same content is in storage
[14:29] <mobrovac> it's an API - so you have to build an application that talks to it
[14:29] <TimStarling> yeah but didn't you previously say that version conversion is not RESTBase's responsibility?
[14:29] <gwicke> TimStarling: we have been discussing a html2html end point, which would convert one version of html/data-parsoid/etc to another
[14:30] <gwicke> yes, the conversion itself is not, but making the request to parsoid to ask for the conversion might be
[14:30] <subbu> mobrovac, testing via browser params vs headers.
[14:30] <subbu> grr.
[14:30] <subbu> in the browser via params
[14:30] <subbu> urls are easy to construct
[14:30] <gwicke> that's all behind the scenes, though
[14:30] <TimStarling> parsoid could provide a format upgrade/downgrade API
[14:30] <DanielK_urlaub> oh right, sorry - i was under the impression that gwicke was proposing to also move the major version marker into the accept header.
[14:30] <gwicke> #link https://phabricator.wikimedia.org/T114413
[14:31] <subbu> TimStarling, yes, we need to provide that.
[14:31] <mobrovac> subbu: that's what curl is here for
[14:31] <mobrovac> :P
[14:31] <subbu> mobrovac, i was afraid you were going to say that. :)
[14:31] <gwicke> TimStarling: ^^ is a task discussing a html2html end point
[14:31] <gwicke> subbu: I agree, that's a strong point for URLs
[14:32] <TimStarling> we could have a testing gateway which does nothing but maps query strings to request headers
[14:32] <DanielK_urlaub> so why not allow both?
[14:32] <TimStarling> if that is really needed
[14:32] <gwicke> a mitigating factor is that the swagger sandbox shows accept headers by default: https://en.wikipedia.org/api/rest_v1/?doc#!/Page_content/get_page_html_title
[14:32] <subbu> TimStarling, fair enough
[14:32] <mobrovac> subbu: with our current content types which contain slashes and whatnot, i'd like to see you uri-enconding that by hand :P
[14:33] <subbu> DanielK_urlaub, you mean by having the query string one to do an internal redirect to the accept header version?
[14:33] <TimStarling> it's pretty normal for REST APIs to be broken when you can't set custom request headers
[14:33] <gwicke> TimStarling: yeah, that could be an option if we can manage to do so without overly complicating the VCL config
[14:33] <mobrovac> exactly TimStarling
[14:33] <TimStarling> and I think gateways are a normal solution to that
[14:34] <gwicke> my proposal would be to start with one option, and consider adding a second alternative in a second step
[14:34] <gwicke> pragmatically, we probably don't have the time to do both at once
[14:34] <mobrovac> nor does it make sense really
[14:35] <gwicke> picking one version doesn't stop us from adding an alternative later
[14:36] <subbu> i think we should move to part (2) of the rfc if part (1) feels resolved .. which it seems it is .. in terms of accept-header being the preferred solution.
[14:36] <mobrovac> s/version/mechanism/ (to avoid confusion)
[14:36] * mobrovac looks forward to (2)
[14:36] <gwicke> TimStarling, DanielK_urlaub: does subbu's summary reflect your view?
[14:38] <DanielK_urlaub> gwicke: yep
[14:38] <TimStarling> yes
[14:38] <gwicke> #summary overall slight preference for going with Accept headers, but option for adding query strings later remains
[14:38] <gwicke> okay, great
[14:38] <gwicke> so, lets move to 2)
[14:39] <DanielK_urlaub> subbu: redirect, rewrite, whatever. can be done by the api itself, or the webserver, or a proxy
[14:39] <gwicke> What to do if no format was specified
[14:39] <subbu> DanielK_urlaub, makes sense.
[14:40] <gwicke> I think general consensus is to strongly encourage clients to specify a version in their request, so that they can benefit from stable / predictable responses
[14:40] <mobrovac> +1
[14:40] <mobrovac> which implies serving the latest version
[14:40] <mobrovac> which i'm +1 for
[14:40] <subbu> i think option 3. from the RFC is really a strawman.
[14:40] <gwicke> one option is to take this even further, to the point of *requiring* clients to specify a version, and reject requests without
[14:40] <subbu> i don't think it needs to be considered.
[14:41] <DanielK_urlaub> gwicke: one way to do that is to make a version-les request redirect to a versioned request. but that only works if the version is in the url
[14:41] <gwicke> DanielK_urlaub: that's effectively the same as returning a specific version
[14:41] <mobrovac> gwicke: requiring them to specify it seems a bit like a high-entry bar
[14:41] <gwicke> which brings us to 1) or 2)
[14:41] <DanielK_urlaub> except that the cleint actually gets told "no, look there!" in http speak.
[14:42] <DanielK_urlaub> option (1) means making the new versio nthe default without giving people a chance to test agains the new version, if i understand correctly
[14:43] <gwicke> DanielK_urlaub: yeah, that's true -- in a URL-based scheme this would also slightly reduce cache fragmentation
[14:43] <gwicke> yes, option (1) very strongly encourages people to set a version explicitly
[14:44] <gwicke> if they don't, then the format can change at relatively short notice
[14:44] <TimStarling> not as strongly as option 3
[14:44] <DanielK_urlaub> ...by breaking their stuff a couple of times...
[14:44] <gwicke> yeah, lets call it "intermediate encouragement"
[14:44] <TimStarling> for the particular change under discussion, I guess option 1 is OK
[14:44] <TimStarling> since a lot of clients are not going to care about data-mw
[14:44] <subbu> right .. option (1) only makes sense when enforced via (3).
[14:45] <DanielK_urlaub> in theory, (2) the the best option. but is it worth the wait, given that people genenrally don't do anything before their stuff breaks, no matter how much you announce?
[14:45] * DanielK_urlaub is one of the people who only notices this tsuff when something breaks
[14:45] <subbu> TimStarling, right .. so the qn. is whether this rfc is deciding a general policy for all future API changes or for this current upcoming one.
[14:45] <gwicke> legoktm brought up the issue of no delay being long enough for everybody
[14:45] <Scott_WUaS> (appreciating the focus of this and recent #wikimedia-office meetings, and the developing phabricator focus too)
[14:45] <TimStarling> in other cases I have argued for a fatal error because terrible things happen when you serve the new API to an old client
[14:46] <TimStarling> terrible as in subtly terrible, which is worse than obviously broken
[14:46] <subbu> i agree .. based on this discussion it seems it is either (2) or (1)+(3).
[14:46] <gwicke> option 2) might encourage clients to not set the explicit version, and rely on announcements instead
[14:48] <TimStarling> 1-2 months is an extremely short deprecation period
[14:48] <gwicke> I'm personally a bit more optimistic than subbu about clients having enough pressure to be explicit with 1)
[14:48] <DanielK_urlaub> gwicke: you could put an annoying warning in every response to an unversioned request. "use the versioned url! we are otherwise not responsible fo rbroken software and curly toenails!"
[14:49] <gwicke> DanielK_urlaub: hehe, yes
[14:49] <Scott_WUaS> :)
[14:49] <gwicke> and.. delay the response by 10s
[14:49] <subbu> gwicke, i guess the question is what I asked TimStarling earlier .. is this about this particular format change only? or is this a policy discussion for all future api changes?
[14:49] <TimStarling> for mobile apps the developer does not fully control the update schedule
[14:49] <DanielK_urlaub> gwicke: limit batch size to 5 ;)
[14:49] <gwicke> subbu: we would like to establish a consistent policy for this
[14:49] <mobrovac> i'd like this to be a general discussion, and not focused on data-mw so much
[14:50] <TimStarling> I don't know what the adoption curve looks like when a new version is pushed out
[14:50] <gwicke> so that we can document expectations, and also be a bit more aggressive about declaring specific entry points stable
[14:50] <subbu> alternatively, we say that decision made here applies to future changes and if necessary, a new rfc gets filed when the policy needs to be amended based on experience .. or maybe that is stating the obvious.
[14:50] <TimStarling> but I know android offers lots of options to limit data usage due to updates, like disabling updates for specific apps or just not scheduling updates at all
[14:51] <gwicke> TimStarling: long-term stability is only possible with an explicit version in the request
[14:51] <gwicke> with that, we also have data about usage of specific versions, which we can use to make decisions about dropping support
[14:52] <subbu> that seems reasonable.
[14:52] <gwicke> so overall I am hearing a concern about clients not being explicit unless forced
[14:53] <gwicke> I guess one option would be to go with strong encouragement first, and then see what the uptake is like
[14:54] <TimStarling> ok
[14:54] <mobrovac> gwicke: but, as DanielK_urlaub pointed out, most people seem to feel concerned only once their stuff break
[14:54] <mobrovac> so in that regard opts (1) and (2) might not be that different after all
[14:54] <subbu> mobrovac, what?
[14:55] <gwicke> yeah, my feeling is also that 2) doesn't add much over 1)
[14:55] <gwicke> the main question seems to be 1) or 3)
[14:55] <subbu> i think i had a preference for option (2) but as gwicke said i am being conservative / not as optimistic as him about client adoption rate in general .. but for the immediate change at hand, it is a non-issue.
[14:56] <mobrovac> subbu: (14:45:26) ***DanielK_urlaub is one of the people who only notices this tsuff when something breaks
[14:56] <subbu> i didn't understand why (1) and (2) are not different at all.
[14:56] <gwicke> such breakage can produce learnable moments™
[14:57] <Scott_WUaS> mobrovac: what else do you have in mind in terms of a general discussion?
[14:57] <mobrovac> subbu: because if you announce it and wait for 2 months, and only once you change it people start reacting then you've effectively wasted 2 months and could have bumped the version in the first place
[14:57] <subbu> there is a delta between when the default format changes ... ah, but i think you guys are saying no one pays attention till stuff breaks.
[14:57] <gwicke> subbu: in terms of how strongly clients are encouraged to be explicit, 2) seems to be slightly weaker than 1)
[14:57] <DanielK_urlaub> subbu: that was the point, yea :)
[14:57] <TimStarling> we're just about out of time
[14:57] <gwicke> while the concern with 2) is that clients not paying attention won't be helped much by a two-month delay
[14:57] <TimStarling> is there an interim solution that everyone is happy with?
[14:58] <mobrovac> Scott_WUaS: nah, i just didn't want the discussion to be confined to the data-mw change at hand
[14:58] <subbu> got it .. i can go with (1).
[14:58] <mobrovac> :)
[14:58] <Scott_WUaS> sounds good
[14:58] <mobrovac> subbu: see, we made you optimistic suddenly :D
[14:58] <subbu> DanielK_urlaub's argument is a good one.
[14:58] <gwicke> yeah
[14:58] <subbu> no, you clarified that my pessimism was warranted. :)
[14:59] <gwicke> how about: we start with option 1), and monitor the percentage of clients who are explicit over the first few changes
[14:59] <gwicke> when take-up is too low and people keep complaining, we revisit and consider switching to 3)
[15:00] <gwicke> does this sound like a sensible approach?
[15:00] <DanielK_urlaub> option 1 sounds fine to me. though it would be nice to give people who *do* pay attention a chance to test. but i guess that would be the people who'd be using a verisoned request in the first place.
[15:00] <subbu> wfm
[15:00] <DanielK_urlaub> so yea.
[15:00] <TimStarling> yes
[15:01] <gwicke> mobrovac: you on board as well?
[15:01] <mobrovac> yup
[15:01] <gwicke> awesome, just in time ;)
[15:01] <mobrovac> but DanielK_urlaub's idea is actually good
[15:01] <TimStarling> documentation is key
[15:01] <mobrovac> that could be achieved by putting it up in labs a week earlier or so
[15:01] <TimStarling> make sure the documentation implies that Accept is required
[15:02] <gwicke> TimStarling: yes, agreed
[15:03] <gwicke> #info broad support for starting with option 1), and monitoring the percentage of clients who are explicit over the first few changes; if take-up is too low and people keep complaining, revisit and consider switching to 3) (enforce version in the request)
[15:03] <TimStarling> make sure you copy the IRC log to the phab event, since there is no meetbot
[15:03] <gwicke> thank you, this was a very productive and enjoyable discussion!
[15:04] <gwicke> TimStarling: yes, will copy a summary & link to a full log
[15:04] <gwicke> #endmeeting

GWicke added a comment.EditedFeb 17 2016, 11:24 PM

Summary from the IRC discussion:

Question 1: How to request a specific response format

Overall there was a slight preference for using the Accept header over query strings for format negotiation. It was noted that support for query strings could be added additionally at a later point.

Question 2: What to do if no format was specified

The main question in the discussion was whether strong encouragement will be enough to persuade clients to explicitly specify a format version. A common concern was that clients without explicit version in the request won't pay attention to announcements either, and will only find out when things break.

There was consensus for starting with strong encouragement and immediate default changes (option 1). If most clients continue to omit explicit versions in their requests & this leads to breakage, then we can reconsider enforcing explicit versions in the request (option 3).

GWicke closed this task as Resolved.Feb 25 2016, 12:44 AM
GWicke updated the task description. (Show Details)
GWicke updated the task description. (Show Details)

I have updated the task description to reflect today's ArchCom decision on this RFC:

  • Use Accept for format negotiation.
  • Strongly encourage users to explicitly request a specific format version, and update the default format without delays.

In the next weeks, we will implement and document this policy, and use it to enable Parsoid's migration of data-mw metadata out of HTML attributes.

Krinkle moved this task from Approved to Implemented on the TechCom-RFC board.
Krinkle edited projects, added TechCom-RFC (TechCom-Approved); removed TechCom-RFC.
Krinkle moved this task from Untriaged to Implemented on the TechCom-RFC (TechCom-Approved) board.