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.
We have two main questions related to this that we would like to ask you for your input on:
## Question 1: 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.
## Question 2: 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 1-2 weeks in advance, and return the latest format version once it is released, or
2) announce and delay changes to the default version for 1-2 months, then change the default format to the latest, or
3) don't allow requests without a specified format version, and return an error.