Page MenuHomePhabricator

Deprecate parsing and diff options in ApiQueryRevisionsBase
Closed, ResolvedPublic

Description

In the action API, there are two ways to parse a page/revision: using action=parse, or using the rvparse parameter to action=query&prop=revisions. Similarly, there are two ways to get a diff: using action=compare, or using parameters such as rvdiffto to action=query&prop=revisions. And then there's action=expandtemplates versus the rvexpandtemplates parameter to prop=revisions. This is a somewhat annoying bit of code duplication.

Further, the prop=revisions versions of these features have somewhat strange behavior. rvparse forces rvlimit=1. rvdiffto and related parameters will sometimes output "notcached" with no way to directly handle the situation.

So, I propose deprecating all of these parameters. The parameters that would be deprecated are the 'rvdifftotext', 'rvdifftotextpst', 'rvdiffto', 'rvexpandtemplates', 'rvgeneratexml', 'rvparse', and 'rvprop=parsetree' parameters to prop=revisions, and the similarly named parameters to prop=deletedrevisions, list=allrevisions, and list=alldeletedrevisions.

Following the normal action API deprecation policy, they'd output warnings but would continue to function until usage drops sufficiently or until it becomes too much trouble to fix them, and they wouldn't receive new feature development.

This would affect the following existing tasks:

Related Objects

Event Timeline

For March 2017, I see the following parameter usage on WMF wikis.

ParameterUsage
rvparse83496915
rvdiffto15640856
rvgeneratexml4781463
rvprop with parsetree2228818
rvexpandtemplates1157821
rvdifftotext86187
rvdifftotextpst31994

It looks like no one is using any of these parameters with prop=deletedrevisions, list=allrevisions, or list=alldeletedrevisions

For reference, the beeline query was

SELECT param, COUNT(1) viewCount
FROM
  wmf_raw.ApiAction
  LATERAL VIEW explode (params) pp as param, value
WHERE
  year = 2017
  AND month = 3
  AND (
    param IN (
      'rvdifftotext', 'arvdifftotext', 'drvdifftotext', 'adrdifftotext', 'grvdifftotext', 'garvdifftotext', 'gdrvdifftotext', 'gadrdifftotext',
      'rvdifftotextpst', 'arvdifftotextpst', 'drvdifftotextpst', 'adrdifftotextpst', 'grvdifftotextpst', 'garvdifftotextpst', 'gdrvdifftotextpst', 'gadrdifftotextpst',
      'rvdiffto', 'arvdiffto', 'drvdiffto', 'adrdiffto', 'grvdiffto', 'garvdiffto', 'gdrvdiffto', 'gadrdiffto',
      'rvexpandtemplates', 'arvexpandtemplates', 'drvexpandtemplates', 'adrexpandtemplates', 'grvexpandtemplates', 'garvexpandtemplates', 'gdrvexpandtemplates', 'gadrexpandtemplates',
      'rvgeneratexml', 'arvgeneratexml', 'drvgeneratexml', 'adrgeneratexml', 'grvgeneratexml', 'garvgeneratexml', 'gdrvgeneratexml', 'gadrgeneratexml',
      'rvparse', 'arvparse', 'drvparse', 'adrparse', 'grvparse', 'garvparse', 'gdrvparse', 'gadrparse'
    )
    OR ( param IN ('rvprop', 'arvprop', 'drvprop', 'adrprop', 'grvprop', 'garvprop', 'gdrvprop', 'gadrprop') AND value like '%parsetree%' )
  )
GROUP BY
  param
;

I use rvparse in my script https://de.wikipedia.org/wiki/Benutzer:Schnark/js/wikiblame.js. This script searches the history of a page for some word to determine when it was added or removed. It can search for that word either in source code or in the rendered content. To do so, I currently use more or less the same query for both modes, and set rvparse to search in the rendered text. Of course I can change the code to use different queries for different modes (and will do so if you decide to really deprecate it), but in this instance, the rvparse parameter feels like the natural thing to use.

Change 351926 had a related patch set uploaded (by Anomie; owner: Anomie):
[mediawiki/core@master] API: Deprecate diff and parse parameters in ApiQueryRevisionsBase

https://gerrit.wikimedia.org/r/351926

BTW: action=parse has with prop=wikitext a way to get the unparsed source of any revision, which (unless you are going to deprecate this, too, in the future to de-duplicate API actions) is a nice solution to my usecase.

Change 351926 merged by jenkins-bot:
[mediawiki/core@master] API: Deprecate diff and parse parameters in ApiQueryRevisionsBase

https://gerrit.wikimedia.org/r/351926

Parameters are now deprecated.

I've only just become aware of this task. I use action=query&prop=revisions with rvdiffto=prev to get diff content for a number of revisions at once. Sometimes it returns notcached for a diff, but it's a good way of getting bulk diffs without imposing a big resource demand.

Now that this is deprecated, as far as I can tell, there's no other way to get the content of more than one revision at once, as action=compare only lets us compare one revision at once. So if I want a collection of diffs, I should do a compare request for each one? Is this really what's intended?

action=compare also appears to have no equivalent to diffto=prev to get a single diff content. What's the right way to get even a single diff of a page, where you only know a single revision id, without using the now-deprecated APIs? Are we supposed to request the page history first to get the adjacent revision ID?

Now that this is deprecated, as far as I can tell, there's no other way to get the content of more than one revision at once, as action=compare only lets us compare one revision at once. So if I want a collection of diffs, I should do a compare request for each one? Is this really what's intended?

Yes, that's what's intended.

action=compare also appears to have no equivalent to diffto=prev to get a single diff content.

The parameter is named torelative and accepts values of prev, next, and cur. See, for example, https://en.wikipedia.org/w/api.php?action=compare&format=jsonfm&fromrev=123456789&torelative=prev.

The JavaScript of "live preview"[1] gets deprecation warnings and has to be updated.

But it seems there is no equivalent for the rvsection parameter?


[1] "Show previews without reloading the page" in Preferences > Editing

Also, documentation needs to be updated: https://www.mediawiki.org/wiki/API:Revisions

(edit: deprecation notes have been added, see this discussion)