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.

API endpoint stability policy

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.

Policy

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-announce mailing lists. Non-breaking changes must be introduced with a minor version bump, and may be announced on wikitech-l and mediawiki-api-announce. Internal implementation changes must be introduced with a patch version bump; the 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-announce mailing lists. Non-breaking changes may be introduced with a minor version bump, and may be announced on wikitech-l and mediawiki-api-announce. 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.

Procedure for deprecating fields and endpoints

Team decides a field/endpoint is deprecated
Team marks the field/endpoint as deprecated in the OpenAPI spec following its patterns
Team member announces the breaking change in the related mailing-lists
If no objection or concern is raised, the team will announce the field/endpoint removal with 2-4 weeks in anticipation
If objections or concerns are identified, further analysis will be conducted to determine next steps (e.g., delay sufficiently, consider alternative implementation strategy, etc.)

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 stability 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.