Summary of existing policies

[edit]

RESTBase API

[edit]

Versioning strategy: Global version in the API path and per-endpoint stability class (stable, unstable, experimental, deprecated)
Breaking change policies
- Stable endpoints: Under semantic versioning, there should be no breaking changes to stable endpoints within a global version.
- Unstable endpoints: The versioning doc states that “We will reach out to users and make a concerted effort to avoid breaking existing consumers.” However it doesn’t specify how these communications will be attempted.
- Experimental and deprecated endpoints: The versioning doc does not include a notification process for breaking changes to experimental endpoints, for marking endpoints as deprecated, or for removing deprecated endpoints.
End of support for output formats: In addition to path-based versioning, some RESTBase API endpoints offer output format versioning through content negotiation. The versioning doc states that “Phased-out formats will be announced with ample warning on the API-announce list.”
Non-breaking change policy: The versioning guide does not provide a notification policy for non-breaking updates to the API. The API documentation does not include a history section to indicate recent changes, and I wasn’t able to find release notes for RESTBase.

MediaWiki REST API

[edit]

Versioning strategy: Global version in the API path, available endpoints based on MediaWiki version
Breaking change policy: Under semantic versioning, there should be no breaking changes within a major version.
Non-breaking change policy: The versioning doc doesn’t specify a notification policy for non-breaking changes. It is implied that the MediaWiki release notes include change updates for the API by MediaWiki version.

Action API

[edit]

Versioning strategy: Versioned with MediaWiki version
Stability guarantees: I wasn’t able to find a stability policy for the Action API, which implies that all documented functionality is considered stable. There seems to be a way to mark a module as internal, but I wasn't able to find any documentation on this.
General updates and announcements policy: The Action API FAQ states that the mediawiki-api-announce mailing list is used for announcements and updates. In addition, changes to the Action API are documented in the release notes (example) and on individual API pages under “parameter history” (example).
Breaking change policy: According to the API roadmap RFC, breaking changes are announced via deprecation warnings, logging of uses of deprecated features, and announcements to mediawiki-api-announce.
Non-breaking change policy: The API roadmap RFC states that minor changes are announced in the mediawiki-api-announce mailing list. However, in practice, media-wiki-announce is usually reserved for breaking changes. Occasionally, important new feature are announced with mediawiki-api-announce.

References

[edit]

Proposed text for Action API change policy page based on API roadmap

[edit]

This page describes the notification process for changes to the Action API. Significant changes to these policies will be announced on the mediawiki-api mailing list and the discussion page.

Minor change policy

[edit]

A minor change is an update that is beneficial for or does not impact API clients. Minor changes must be backwards compatible with current API behavior and can include adding an optional parameter, including more information in a response, or adding API functionality.

Minor changes are announced to the mediawiki-api mailing list. New parameters are documented in the MediaWiki release notes and the parameter history sections on the API pages. For example, see the parameter history for the edit module.

Breaking change policy

[edit]

A breaking change is an update that violates existing API guarantees or modifies API behavior in a backwards-incompatible way. For example, removing a parameter or response property, deprecating a feature, and changing an error code are considered breaking changes.

Breaking changes are announced in advance on the mediawiki-api-announce mailing list. These announcements have the word BREAKING in the subject line. Deprecated parameters are documented in the MediaWiki release notes and the parameter history sections on the API pages.

Feature deprecation

[edit]

When it is possible for the new version of a feature to coexist with the old (e.g. prop=imageinfo and prop=fileinfo):

The new feature will be implemented.
The deprecation will be announced:
- A message will be sent to the mediawiki-api-announce mailing list.
- The old feature will report deprecation warnings.
- Uses of the deprecated feature will be logged to the api-feature-usage log channel or, for client developers on Wikimedia sites, to Special:ApiFeatureUsage.
After a suitable timeframe (e.g. if the deprecation was in MediaWiki 1.24, during the 1.25 development cycle), usage of the deprecated feature on WMF wikis will be evaluated and the deprecated feature may be removed.

When it is not possible for the new version to coexist with the old:

The new feature will be implemented, but must be explicitly requested by clients via a query parameter.
The deprecation will be announced:
- A message will be sent to the mediawiki-api-announce mailing list.
- Deprecation warnings will be output when the parameter to request the new version is not given.
- Uses of the deprecated feature will be logged privately.
After a suitable timeframe, the new version will become the default and the old removed. The "request the new version" parameter will be silently ignored.
The "request the new version" parameter will at some point be removed, leading to "unrecognized parameter" warnings.

In rare cases, it may not be possible to follow the deprecation policy, such as for a breaking change due to security issue. In this case, a message will be sent to the mediawiki-api-announce mailing list with details about the change and the planned Wikimedia deployment schedule.

Changes to default behavior

[edit]

When the default for a behavior is to be changed but the old behavior is not being removed (e.g. changing the default continuation to be the new easy-to-use style rather than the current query-continue):

If not already present, a request parameter will be added to specifically request the old behavior.
The change will be announced:
- A message will be sent to the mediawiki-api-announce mailing list.
- Deprecation warnings will be output when neither the select-new-version nor the select-old-version flags are used. Logs will also be made.
After a suitable timeframe, the new version will become the default.
Any flag to select the new version explicitly may at some point be removed, leading to "unrecognized parameter" warnings.