API: Change default continuation format for action=query

The new format is much easier to use correctly, and should therefore be
the default. The old format is maintained for clients that need the
additional flexibility.

Bug: T96858
Change-Id: I984e63581f4ef23ccada916b6d45131d1fb5e001

diff --git a/RELEASE-NOTES-1.26 b/RELEASE-NOTES-1.26
index 896d1d5..2dc1338 100644 (file)
--- a/RELEASE-NOTES-1.26
+++ b/RELEASE-NOTES-1.26
@@ -11,6 +11,9 @@ production.
 === Configuration changes in 1.26 ===
 * $wgEnableParserCache was deprecated, set $wgParserCacheType to CACHE_NONE
   instead if you want to disable the parser cache.
+* New-style continuation is now the default for API action=continue. Clients may
+  use the 'rawcontinue' parameter to receive raw query-continue data, but the
+  new style is encouraged as it's harder to implement incorrectly.
 
 === New features in 1.26 ===
 * Change tags can now be hidden in the interface by disabling the associated
@@ -35,6 +38,9 @@ production.
 * (T65198) Talk page tabs now have a "rel=discussion" attribute
 
 === Action API changes in 1.26 ===
+* New-style continuation is now the default for action=continue. Clients may
+  use the 'rawcontinue' parameter to receive raw query-continue data, but the
+  new style is encouraged as it's harder to implement incorrectly.
 * API action=query&list=tags: The displayname can now be boolean false if the
   tag is meant to be hidden from user interfaces.
 * action=import no longer allows both the namespace= and rootpage= parameters

diff --git a/includes/api/ApiQuery.php b/includes/api/ApiQuery.php
index 304d0f0..5378e92 100644 (file)
--- a/includes/api/ApiQuery.php
+++ b/includes/api/ApiQuery.php
@@ -292,7 +292,7 @@ class ApiQuery extends ApiBase {
 
                // Write the continuation data into the result
                $this->setContinuationManager( null );
-               if ( $this->mParams['continue'] === null ) {
+               if ( $this->mParams['rawcontinue'] ) {
                        $data = $continuationManager->getRawContinuation();
                        if ( $data ) {
                                $this->getResult()->addValue( null, 'query-continue', $data,
@@ -302,15 +302,14 @@ class ApiQuery extends ApiBase {
                        $continuationManager->setContinuationIntoResult( $this->getResult() );
                }
 
+               /// @todo: Remove this after a suitable period of time. When REL1_26 is cut, if not before.
                if ( $this->mParams['continue'] === null && !$this->mParams['rawcontinue'] &&
-                       $this->getResult()->getResultData( 'query-continue' ) !== null
+                       $this->getResult()->getResultData( 'continue' ) !== null
                ) {
-                       $this->logFeatureUsage( 'action=query&!rawcontinue&!continue' );
                        $this->setWarning(
-                               'Formatting of continuation data will be changing soon. ' .
-                               'To continue using the current formatting, use the \'rawcontinue\' parameter. ' .
-                               'To begin using the new format, pass an empty string for \'continue\' ' .
-                               'in the initial query.'
+                               'Formatting of continuation data has changed. ' .
+                               'To receive raw query-continue data, use the \'rawcontinue\' parameter. ' .
+                               'To silence this warning, pass an empty string for \'continue\' in the initial query.'
                        );
                }
        }
@@ -485,7 +484,7 @@ class ApiQuery extends ApiBase {
        public function setGeneratorContinue( $module, $paramName, $paramValue ) {
                wfDeprecated( __METHOD__, '1.24' );
                $this->getContinuationManager()->addGeneratorContinueParam( $module, $paramName, $paramValue );
-               return $this->getParameter( 'continue' ) !== null;
+               return !$this->getParameter( 'rawcontinue' );
        }
 
        /**
@@ -549,7 +548,9 @@ class ApiQuery extends ApiBase {
                        'export' => false,
                        'exportnowrap' => false,
                        'iwurl' => false,
-                       'continue' => null,
+                       'continue' => array(
+                               ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
+                       ),
                        'rawcontinue' => false,
                );
                if ( $flags ) {

diff --git a/includes/api/i18n/en.json b/includes/api/i18n/en.json
index caad49f..792febc 100644 (file)
--- a/includes/api/i18n/en.json
+++ b/includes/api/i18n/en.json
@@ -355,8 +355,7 @@
        "apihelp-query-param-export": "Export the current revisions of all given or generated pages.",
        "apihelp-query-param-exportnowrap": "Return the export XML without wrapping it in an XML result (same format as [[Special:Export]]). Can only be used with $1export.",
        "apihelp-query-param-iwurl": "Whether to get the full URL if the title is an interwiki link.",
-       "apihelp-query-param-continue": "When present, formats query-continue as key-value pairs that should simply be merged into the original request. This parameter must be set to an empty string in the initial query.\n\nThis parameter is recommended for all new development, and will be made default in the next API version.",
-       "apihelp-query-param-rawcontinue": "Currently ignored. In the future, <var>$1continue</var> will become the default and this will be needed to receive the raw <samp>query-continue</samp> data.",
+       "apihelp-query-param-rawcontinue": "Return raw <samp>query-continue</samp> data for continuation.",
        "apihelp-query-example-revisions": "Fetch [[Special:ApiHelp/query+siteinfo|site info]] and [[Special:ApiHelp/query+revisions|revisions]] of <kbd>Main Page</kbd>.",
        "apihelp-query-example-allpages": "Fetch revisions of pages beginning with <kbd>API/</kbd>.",
 

diff --git a/includes/api/i18n/qqq.json b/includes/api/i18n/qqq.json
index f690cf4..051ef07 100644 (file)
--- a/includes/api/i18n/qqq.json
+++ b/includes/api/i18n/qqq.json
@@ -331,7 +331,6 @@
        "apihelp-query-param-export": "{{doc-apihelp-param|query|export}}",
        "apihelp-query-param-exportnowrap": "{{doc-apihelp-param|query|exportnowrap}}",
        "apihelp-query-param-iwurl": "{{doc-apihelp-param|query|iwurl}}",
-       "apihelp-query-param-continue": "{{doc-apihelp-param|query|continue}}",
        "apihelp-query-param-rawcontinue": "{{doc-apihelp-param|query|rawcontinue}}",
        "apihelp-query-example-revisions": "{{doc-apihelp-example|query}}",
        "apihelp-query-example-allpages": "{{doc-apihelp-example|query}}",

diff --git a/tests/phpunit/includes/api/query/ApiQueryContinueTestBase.php b/tests/phpunit/includes/api/query/ApiQueryContinueTestBase.php
index ce2f70d..db61bc8 100644 (file)
--- a/tests/phpunit/includes/api/query/ApiQueryContinueTestBase.php
+++ b/tests/phpunit/includes/api/query/ApiQueryContinueTestBase.php
@@ -57,10 +57,9 @@ abstract class ApiQueryContinueTestBase extends ApiQueryTestBase {
                } else {
                        $params['action'] = 'query';
                }
-               if ( $useContinue && !isset( $params['continue'] ) ) {
+               // Silence warning
+               if ( !isset( $params['continue'] ) ) {
                        $params['continue'] = '';
-               } else {
-                       $params['rawcontinue'] = '1';
                }
                $count = 0;
                $result = array();

diff --git a/tests/phpunit/includes/api/query/ApiQueryTestBase.php b/tests/phpunit/includes/api/query/ApiQueryTestBase.php
index 9e830f2..d5fa454 100644 (file)
--- a/tests/phpunit/includes/api/query/ApiQueryTestBase.php
+++ b/tests/phpunit/includes/api/query/ApiQueryTestBase.php
@@ -87,6 +87,7 @@ STR;
 
        /**
         * Checks that the request's result matches the expected results.
+        * Assumes no rawcontinue and a complete batch.
         * @param array $values Array is a two element array( request, expected_results )
         * @param array $session
         * @param bool $appendModule
@@ -99,8 +100,9 @@ STR;
                if ( !array_key_exists( 'action', $req ) ) {
                        $req['action'] = 'query';
                }
-               if ( !array_key_exists( 'continue', $req ) ) {
-                       $req['rawcontinue'] = '1';
+               // Silence warning
+               if ( !isset( $params['continue'] ) ) {
+                       $params['continue'] = '';
                }
                foreach ( $req as &$val ) {
                        if ( is_array( $val ) ) {
@@ -108,7 +110,7 @@ STR;
                        }
                }
                $result = $this->doApiRequest( $req, $session, $appendModule, $user );
-               $this->assertResult( array( 'query' => $exp ), $result[0], $req );
+               $this->assertResult( array( 'batchcomplete' => true, 'query' => $exp ), $result[0], $req );
        }
 
        protected function assertResult( $exp, $result, $message = '' ) {