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:
- A query parameter to request a specific format version.
- 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:
- Announce new format versions as early as possible before deployment, and return the latest deployed format version when no explicit version was specified.
- Announce and delay changes to the default format version for 1-2 months.
- 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).