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.

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.
 * Link to the MediaWiki.org endpoint documentation from each OpenAPI / Swagger spec
 * Specify recommended email list for being notified of breaking changes from each OpenAPI / Swagger spec
 * Specify recommended email list for being notified of breaking changes from the MediaWiki.org pages

Deprecation and removal announcements

 * API endpoints should be marked as deprecated as soon as the team agrees that they should be removed at some point in the future, even if there is no specific plan or deadline for their removal.
 * Removal of public endpoints should be announced on wikitech-l and mediawiki-api-announce at least two weeks in advance of the change, even if the affected endpoints are marked experimental.