API versioning

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

Global API version
The global API version is part of the path. Example:. 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.

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/1.2.1 " For longer-term output format stability, you should send an  header with the mime type you