Requests for comment/API roadmap
| API roadmap | |
|---|---|
| Component | General |
| Creation date | |
| Author(s) | Anomie, Yurik |
| Document status | accepted See Phabricator. |
Background
editMediaWiki 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
editDiscussion 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):
- 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 on the server (currently in WMF's case this is on fluorine where deployers have access).
- 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.
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.
Architectural changes
editChanges reviewed for this RFC include:
- Removal of obsolete output formats
- Replacing format=json to clean up cruft inherited from its origin as a dump of data intended for XML output
- The same for format=php
- Adjusting format=xml to no longer throw exceptions if hoops aren't jumped through
- Defining JSON as the preferred output format, and making format=jsonfm the default
- Don't try to syntax-highlight pretty-printed output in core
- HTMLification, pagination, and i18n of action=help
- I18n for warnings and errors
- Officially support uselang
- Removal of long-deprecated parameters
- Simplified continuation as default for action=query
- Rewrite prop=imageinfo from scratch as prop=fileinfo
- A few other enhancements that crept into the RFC when it was being treated as a TODO list.
Full details are at API/Architecture work and API/Architecture work/Planning.