RFC: Defining a policy for REST API result format versioning / negotiation

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

RFC: Defining a policy for REST API result format versioning / negotiation

Gabriel Wicke-3
Hi,

we are considering a policy for REST API end point result format
versioning and negotiation. The background and considerations are
spelled out in a task and mw.org page:

https://phabricator.wikimedia.org/T124365
https://www.mediawiki.org/wiki/Talk:API_versioning

Based on the discussion so far, have come up with the following
candidate solution:

1) Clearly advise clients to explicitly request the expected mime type
with an Accept header. Support older mime types (with on-the-fly
transformations) until usage has fallen below a very low percentage,
with an explicit sunset announcement.

2) Always return the latest content type if no explicit Accept header
was specified.

We are interested in hearing your thoughts on this.

Once we have reached rough consensus on the way forward, we intend to
apply the newly minted policy to an evolution of the Parsoid HTML
format, which will move the data-mw attribute to a separate metadata
blob.

Gabriel Wicke

_______________________________________________
Mediawiki-api mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Defining a policy for REST API result format versioning / negotiation

Gabriel Wicke-3
We will discuss options for REST API response format versioning and
-negotiation in Wednesday's RFC meeting:

Topic: https://phabricator.wikimedia.org/T124365
Time: Wednesday 22:00 UTC (2pm PST)
Location: #wikimedia-office IRC channel

This RFC will then enter its one-week Final Comment Period, after
which the Architecture Committee will decide based on the discussion.

I'm looking forward to your input on the task or IRC.

Gabriel

On Thu, Jan 21, 2016 at 4:29 PM, Gabriel Wicke <[hidden email]> wrote:

> Hi,
>
> we are considering a policy for REST API end point result format
> versioning and negotiation. The background and considerations are
> spelled out in a task and mw.org page:
>
> https://phabricator.wikimedia.org/T124365
> https://www.mediawiki.org/wiki/Talk:API_versioning
>
> Based on the discussion so far, have come up with the following
> candidate solution:
>
> 1) Clearly advise clients to explicitly request the expected mime type
> with an Accept header. Support older mime types (with on-the-fly
> transformations) until usage has fallen below a very low percentage,
> with an explicit sunset announcement.
>
> 2) Always return the latest content type if no explicit Accept header
> was specified.
>
> We are interested in hearing your thoughts on this.
>
> Once we have reached rough consensus on the way forward, we intend to
> apply the newly minted policy to an evolution of the Parsoid HTML
> format, which will move the data-mw attribute to a separate metadata
> blob.
>
> Gabriel Wicke



--
Gabriel Wicke
Principal Engineer, Wikimedia Foundation

_______________________________________________
Mediawiki-api mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Defining a policy for REST API result format versioning / negotiation

Gabriel Wicke-3
The IRC discussion just finished, thanks to everybody who
participated! You can read a full log on the task [1]. Here is a short
summary:

== 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 can 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 quick
default changes. If most clients continue to omit explicit versions in
their requests, then we can reconsider *forcing* clients to supply a
version.

== Next steps ==

The Architecture Committee will officially decide this matter based on
the discussion at next Wednesday's meeting.

Gabriel

[1]: https://phabricator.wikimedia.org/T124365#2036959

On Mon, Feb 15, 2016 at 7:41 PM, Gabriel Wicke <[hidden email]> wrote:

> We will discuss options for REST API response format versioning and
> -negotiation in Wednesday's RFC meeting:
>
> Topic: https://phabricator.wikimedia.org/T124365
> Time: Wednesday 22:00 UTC (2pm PST)
> Location: #wikimedia-office IRC channel
>
> This RFC will then enter its one-week Final Comment Period, after
> which the Architecture Committee will decide based on the discussion.
>
> I'm looking forward to your input on the task or IRC.
>
> Gabriel
>
> On Thu, Jan 21, 2016 at 4:29 PM, Gabriel Wicke <[hidden email]> wrote:
>> Hi,
>>
>> we are considering a policy for REST API end point result format
>> versioning and negotiation. The background and considerations are
>> spelled out in a task and mw.org page:
>>
>> https://phabricator.wikimedia.org/T124365
>> https://www.mediawiki.org/wiki/Talk:API_versioning
>>
>> Based on the discussion so far, have come up with the following
>> candidate solution:
>>
>> 1) Clearly advise clients to explicitly request the expected mime type
>> with an Accept header. Support older mime types (with on-the-fly
>> transformations) until usage has fallen below a very low percentage,
>> with an explicit sunset announcement.
>>
>> 2) Always return the latest content type if no explicit Accept header
>> was specified.
>>
>> We are interested in hearing your thoughts on this.
>>
>> Once we have reached rough consensus on the way forward, we intend to
>> apply the newly minted policy to an evolution of the Parsoid HTML
>> format, which will move the data-mw attribute to a separate metadata
>> blob.
>>
>> Gabriel Wicke
>
>
>
> --
> Gabriel Wicke
> Principal Engineer, Wikimedia Foundation



--
Gabriel Wicke
Principal Engineer, Wikimedia Foundation

_______________________________________________
Mediawiki-api mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Defining a policy for REST API result format versioning / negotiation

Gabriel Wicke-3
At the conclusion of the Final Comment Period, the Architecture
Committee today decided to accept the policy as summarized in my last
mail:

- Use `Accept` headers for format negotiation.
- Strongly encourage users to explicitly request a specific format
version, and update the default format promptly.

We will now document and implement this policy. The first use of
content negotiation will be an upcoming change in Parsoid's HTML
format.

Thank you for your input,

Gabriel


On Wed, Feb 17, 2016 at 3:36 PM, Gabriel Wicke <[hidden email]> wrote:

> The IRC discussion just finished, thanks to everybody who
> participated! You can read a full log on the task [1]. Here is a short
> summary:
>
> == 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 can 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 quick
> default changes. If most clients continue to omit explicit versions in
> their requests, then we can reconsider *forcing* clients to supply a
> version.
>
> == Next steps ==
>
> The Architecture Committee will officially decide this matter based on
> the discussion at next Wednesday's meeting.
>
> Gabriel
>
> [1]: https://phabricator.wikimedia.org/T124365#2036959
>
> On Mon, Feb 15, 2016 at 7:41 PM, Gabriel Wicke <[hidden email]> wrote:
>> We will discuss options for REST API response format versioning and
>> -negotiation in Wednesday's RFC meeting:
>>
>> Topic: https://phabricator.wikimedia.org/T124365
>> Time: Wednesday 22:00 UTC (2pm PST)
>> Location: #wikimedia-office IRC channel
>>
>> This RFC will then enter its one-week Final Comment Period, after
>> which the Architecture Committee will decide based on the discussion.
>>
>> I'm looking forward to your input on the task or IRC.
>>
>> Gabriel
>>
>> On Thu, Jan 21, 2016 at 4:29 PM, Gabriel Wicke <[hidden email]> wrote:
>>> Hi,
>>>
>>> we are considering a policy for REST API end point result format
>>> versioning and negotiation. The background and considerations are
>>> spelled out in a task and mw.org page:
>>>
>>> https://phabricator.wikimedia.org/T124365
>>> https://www.mediawiki.org/wiki/Talk:API_versioning
>>>
>>> Based on the discussion so far, have come up with the following
>>> candidate solution:
>>>
>>> 1) Clearly advise clients to explicitly request the expected mime type
>>> with an Accept header. Support older mime types (with on-the-fly
>>> transformations) until usage has fallen below a very low percentage,
>>> with an explicit sunset announcement.
>>>
>>> 2) Always return the latest content type if no explicit Accept header
>>> was specified.
>>>
>>> We are interested in hearing your thoughts on this.
>>>
>>> Once we have reached rough consensus on the way forward, we intend to
>>> apply the newly minted policy to an evolution of the Parsoid HTML
>>> format, which will move the data-mw attribute to a separate metadata
>>> blob.
>>>
>>> Gabriel Wicke
>>
>>
>>
>> --
>> Gabriel Wicke
>> Principal Engineer, Wikimedia Foundation
>
>
>
> --
> Gabriel Wicke
> Principal Engineer, Wikimedia Foundation



--
Gabriel Wicke
Principal Engineer, Wikimedia Foundation

_______________________________________________
Mediawiki-api mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-api