Requests for comment/API roadmap

Request for comment (RFC)
API roadmap
Component General
Creation date
Author(s) Anomie, Yurik
Document status accepted
See Phabricator.

Background

edit

MediaWiki API has been steadily growing and adding features, and even though it provides most of the desired functionality, it has some areas in which it could be improved.

This RFC proposes making some significant changes to the API, along with a process for handling deprecations.

Deprecation process

edit
Historical; the canonical location for the deprecation process is API:Deprecation

Discussion at the Architecture Summit in January 2014 was generally favorable to deprecations of major features, as long as we give people enough time to update. Minor changes will continue to be announced to the mediawiki-api-announce mailing list.

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

  1. The new feature will be implemented.
  2. 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 on the server (currently in WMF's case this is on fluorine where deployers have access).
  3. 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:

  1. The new feature will be implemented, but must be explicitly requested by clients via a query parameter.
  2. 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.
  3. 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.
  4. The "request the new version" parameter will at some point be removed, leading to "unrecognized parameter" warnings.

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):

  1. If not already present, a request parameter will be added to specifically request the old behavior.
  2. 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.
  3. After a suitable timeframe, the new version will become the default.
  4. Any flag to select the new version explicitly may at some point be removed, leading to "unrecognized parameter" warnings.

Architectural changes

edit

Changes reviewed for this RFC include:

Full details are at API/Architecture work and API/Architecture work/Planning.

See also

edit