The REST API has been following an [API versioning policy](https://www.mediawiki.org/wiki/API_versioning). 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.
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.
Apart from a mechanism to indicate the specific return format, we need to decide which format to return if no specific version is requested. The main options are:
1) Return the latest format version by default, or
2) announce changes to the default version in advance, then change it.