Jump to content

API/Deprecation

From mediawiki.org
< API

Overview

[edit]

As Wikimedia project needs evolve, so must the APIs that we offer. This includes deprecating and removing some existing capabilities as a means of simplifying and improving our API offerings while making them more sustainable.

This document is intended to outline deprecation as part of the MediaWiki approach to API lifecycle management and versioning. For now, the following APIs are considered to be in scope for this policy:

Functional expectations

[edit]

Upcoming deprecations will be announced through the standard API communication channels. In most cases, deprecated endpoints will have a clear alternative solution. If no clear alternative solution is available, we will provide guides for users who need to maintain similar functionality. Migration guides will typically be linked through the standard API communication channels when necessary.

Once implemented, deprecations will be captured and communicated officially in the following ways:

The expected duration for the deprecation period prior to removal will be included in the technical community announcements, but we will typically support a transition period of at least 3 months between deprecating and removing API properties. In cases of more heavily adopted or impactful endpoints, the timeline may be longer. Additionally, there may be some cases where the timeline is accelerated (see FAQ: How long between announcing a deprecation and actually removing the endpoint?).

The role of versioning

[edit]

In terms of versioning, we consider deprecations to be a minor change, whereas actually disabling an endpoint may be considered a major version change.

Most Wikimedia APIs already reflect the major version as part of the URL (for example, rest_v1 for Analytics and RESTBase APIs; rest.php/v1 for MediaWiki REST). However, they are currently at a very high granularity; many unrelated endpoints are under the same version indicator, which limits our ability to elegantly target and version the available endpoints.

Selective deprecation disclaimer

[edit]

Although we aspire to strictly enforce versioning as much as possible within the new API modules, we also recognize that new versions are disruptive for developers. In some cases where endpoints or properties are infrequently used, we may choose to deprecate and remove API functionality without incrementing a major version. In these cases, we will proactively communicate and support migrations for developers relying on the deprecation target in addition to providing an expected migration and sunsetting timeline (typically at least 3 months).

FAQ

[edit]

Why is deprecation necessary?

[edit]

Decades of organic growth without centralized API governance led to fragmented, bespoke implementations that now hinder technical agility and standardization. Beyond that, maintaining services is not free; we are paying for duplicative infrastructure costs, as well as the expertise that must be learned in order to maintain the capabilities. To reduce maintenance costs and ensure a seamless developer experience, we are simplifying our API infrastructure and bringing greater consistency across all APIs, which in some cases will mean deprecating duplicative, lesser used, and lesser loved endpoints or API modules.

There are many reasons why a given endpoint or API module might be deprecated:

  • A new version improves usability, security, or consistency with other areas of the API.
  • URL structures and service locations are changing.
  • It is functionally duplicative of another endpoint or technical capability.
  • An API endpoint or property introduces complexity without providing demonstrable value; it is infrequently used yet expensive to run or maintain.

What can be deprecated?

[edit]

We may deprecate the following items, ordered from most broad to most specific:

  • API modules
  • Endpoints
  • Request parameters
  • Individual response object properties

What are the standard API communication channels?

[edit]

All developer facing API changes (including minor changes, deprecation, deactivation, and versioning) will be announced through the standard technical volunteer and API announcement channels:

Will deprecation always result in a new version of the OpenAPI specification?

[edit]

Not yet, but ideally in the future. We are still working through internal policies and procedures for how to appropriately apply semantic versioning to the spec when individual APIs are registered and updated by disparate teams. Keep an eye on the API changelog and this document for more information about changes to spec semantic versioning.

Will deprecation always result in a new version of the API?

[edit]

Ideally. However, we have a lot of clean up and consolidation to do in the immediate future. To reduce the overall fatigue and churn for our technical volunteers, bot maintainers, and tool developers, there may be some specific cases where we choose to deprecate and remove functionality for lesser used endpoints, without incrementing the major version overall. These changes will be communicated early, often, and clearly across our standard API communication channels.

How long between announcing a deprecation and actually removing the endpoint?

[edit]

The time between deprecation announcements and actual sunsetting will typically be at least 3 months. However, there may be some execeptions, where faster deprecation periods are required. Exceptions to this rule may include:

  • Security or privacy issues
  • Extremely low utilization rates
  • Scalability or performance issues
  • Beta and experimental endpoints
  • In these cases, we will proactively communicate the expected sunsetting timelines along with the deprecation announcements.

How does this relate to existing stability policies?

[edit]
Tracked in Phabricator
Task T408162

The long term goal of this work is to consolidate deprecation processes and clarify expectations across Wikimedia APIs. In addition to the global API Usage Policy, several APIs across Wikimedia have published their own versioning and stability policies. Existing versioning & stability policies and procedures that may eventually be replaced or merged with these processes include:

The Action API is considered to be unversioned; it pre-dates standards for API versioning and is expected to remain relatively stable over time. Although not formally documented, historic breaking changes have been communicated and implemented without formal versioning. Instead, it is tightly coupled with the version of MediaWiki that it is running on.

What are API modules?

[edit]

The MediaWiki Interfaces team plans to break down existing APIs into modules that reflect bundles of related capabilities. These modules will support more granular and independent versioning, in addition to allowing for more distributed ownership with clearer boundaries across teams. This means that if a given module needs to introduce a breaking change, other modules remain unaffected.

Additional API modules are still very exploratory. They will be introduced as new API versions (likely starting as beta) at a future date.

Retrieved from "https://www.mediawiki.org/w/index.php?title=API/Deprecation&oldid=7963332"