API versioning

This page describes the API versioning policy for RESTBase (aka Wikimedia REST API), which are documented at /api/rest_v1/?doc for each wiki.

Global API version

The global API version is part of the path. Example: /v1/. Following the principles of semantic versioning, it is incremented when a stable end point is changed in a backwards-incompatible manner. For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways. Content types are versioned using content negotiation, and do not trigger global version increments. Since the introduction of a new major API version is a very disruptive event, we try hard to avoid breaking stable end points.

End point stability

Each API end point is marked with a stability class: Stable, unstable, experimental or deprecated. Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.

Stable

Stable end points are guaranteed to not change in incompatible ways. This means that you can be sure that the basic interface as documented by the spec will continue to work as described.

Unstable

End points marked as unstable can change in incompatible ways without incrementing the major API version, but they will increment minor versions. We will reach out to users and make a concerted effort to avoid breaking existing consumers.

Experimental

Experimental end points can change in incompatible ways at any time, without incrementing the API version. You are welcome to use them at your own risk.

Deprecated

If an end point is marked as deprecated, it means that it has not been useful to clients and will consequently be removed in the near future. If your code is using such an end point, you should stop using it as soon as possible. We will always make sure to provide users with alternative ways of obtaining the same information.

Content format stability and negotiation

Changes in the structure of the returned content will be clearly indicated by a change in the profile part of the MIME type:

text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/2.0.0"

For longer-term output format stability, you should send an Accept header with the MIME type you expect:

Accept: text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/2.0.0"

In case of output format changes, the API will then continue to respond with the requested format (subject to semantic versioning protocol, see below), even if a newer format is available. Support for old output formats will normally be maintained until usage drops below a low threshold. Phased-out formats will be announced with ample warning on the API-announce list.

Background: How we interpret semver in format negotiations

Our profile URLs generally end with a version number based on the semver semantic versioning scheme. In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0). As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on. Clients are encouraged to provide the exact version they tested with, but the API will typically return the latest content-type that is compatible with the requested major version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.

The exact protocol is:

1. If client-requested version is matching semver major version and has lower minor version then stored - return stored content
2. If the client-requested version is semver major or minor greater then stored version - update the content
   1. If updated content is matching requested major version and has higher or equal minor version - return
   2. If updated content has lower major or minor version - return 406 error
   3. If updated content has higher major version - go to point 3.
3. If requested version is semver major lower then stored - transform content to downgrade.

See also

• The Specs page hierarchy on this wiki documents versioned content formats.
• See this RFC discussion as well as this section of this article's talk page for background on how we arrived at the format versioning strategy outlined here.