Wikimedia Product/Wikimedia Product Infrastructure team/API endpoint stability policy

The team has agreed on the following procedures with respect to documenting endpoint stability and deprecating and removing publicly exposed API endpoints.

Scope
This policy applies to all API endpoints served by components maintained by the Product Infrastructure team (see Component responsibility).

Definitions

 * breaking change: a breaking change here means any non-additive change to an API interface, including the removal of fields or the removal of an endpoint in its entirety.

Stable
A stable endpoint is expected to change only rarely and in non-breaking ways, and may be used with confidence by client applications. Any breaking changes must be introduced with a major version bump, and must be announced at least one month in advance on the wikitech-l and mediawiki-api mailing lists. Non-breaking changes must be introduced with a minor version bump, and may be announced on wikitech-l and mediawiki-api. Internal implementation changes must be introduced with a patch version bump; announcement of such changes is at the team's discretion.

Unstable
An unstable endpoint is substantially complete but may be subject to relatively frequent changes due to bug fixes or client-requested changes to its interface. Any breaking changes must be introduced with a minor version bump, and must be announced at least two weeks in advance on the wikitech-l and mediawiki-api mailing lists. Non-breaking changes may be introduced with a minor version bump, and may be announced on wikitech-l and mediawiki-api. Internal implementations may change at any time with no version bump or announcement.

Experimental
An experimental endpoint is under active development or initial adoption by an internal client, and is subject to change, including in breaking ways, at any time. Clients should use an experimental endpoint at their own risk. Changes (breaking or non-breaking) may be accompanied by a version bump and may be announced at the team's discretion.

Deprecated
A deprecated endpoint is one that the team plans to remove at some point in the future (but not necessarily the near future). Clients should contact the team to discuss their plans before consuming a deprecated API endpoint.

Documentation

 * The Page Content Service page should advertise the stability of the public API endpoints. Where the stability is anything less than "stable," the stability level should be featured prominently through visual indicators.
 * This stabilility policy should be linked from each OpenAPI / Swagger spec.
 * Each OpenAPI / Swagger spec should also specify the mailing lists to follow for notifications of breaking changes.