API: Internal cleanup
authorBrad Jorsch <bjorsch@wikimedia.org>
Wed, 27 Aug 2014 19:41:05 +0000 (15:41 -0400)
committerBrad Jorsch <bjorsch@wikimedia.org>
Wed, 27 Aug 2014 20:18:19 +0000 (16:18 -0400)
* Separate client-visible and internal release notes, because there are
  a lot of both and will be more coming up
* Correct errors in release notes
* Add detail on token changes to release notes
* List deprecated API classes and methods in release notes
* Add missing @deprecated on ApiFormat* classes

Change-Id: I577f3c8b9182f1625470c8bc52d3bdfe5d623d81

RELEASE-NOTES-1.24
includes/api/ApiFormatDbg.php
includes/api/ApiFormatDump.php
includes/api/ApiFormatTxt.php
includes/api/ApiFormatWddx.php
includes/api/ApiFormatYaml.php

index c4822d3..ff9cf83 100644 (file)
@@ -175,7 +175,7 @@ production.
   bar using the HTML5 History API. When [[Dog]] redirects to [[Animals#Dog]],
   the user will now see "Animals#Dog" in their browser instead of "Dog#Dog".
 * API token handling has been rewritten. Any API module using tokens will need
-  to be updated.
+  to be updated. See the entry below under "Action API internal changes".
 * Added HTMLAutoCompleteSelectField.
 
 === Bug fixes in 1.24 ===
@@ -210,20 +210,20 @@ production.
 * (bug 69789) Title::getContentModel() now loads from the database when
   necessary instead of incorrectly returning the default content model.
 
-=== Web API changes in 1.24 ===
+=== Action API changes in 1.24 ===
 * action=parse API now supports prop=modules, which provides the list of
   ResourceLoader modules that should be used to enhance the parsed content.
 * action=query&meta=siteinfo&siprop=interwikimap returns a new "protorel"
-  field which is true iff protocol-relative urls can be used to access
+  field which is true if protocol-relative urls can be used to access
   a particular interwiki map entry.
-* ApiQueryLogEvents now provides logpage, which is the page ID from the
+* list=logevents now provides logpage, which is the page ID from the
   logging table, if ids are requested and the user has the permissions.
 * action=edit now requires that appendtext, prependtext, or section=new be used
   when using the 'redirect' parameter, to prevent clients accidentally
   overwriting the target page with the content of the redirect.
-* action=logevents will now return an error if both letitle and leprefix are
+* list=logevents will now return an error if both letitle and leprefix are
   specified.
-* action=logevents has a new parameter, lenamespace, to allow filtering by
+* list=logevents has a new parameter, lenamespace, to allow filtering by
   namespace.
 * action=expandtemplates has a new parameter, prop, and a new output format.
   The old format is still used if prop isn't provided, but this is deprecated.
@@ -235,22 +235,11 @@ production.
 * (bug 60734) Actions that use ApiPageSet (e.g. purge, watch,
   setnotificationtimestamp) will now include continuation information when
   using a generator.
-* $wgAPIModules (and the related $wgAPIFormatModules, $wgAPIMetaModules,
-  $wgAPIPropModules, and $wgAPIListModules settings) now allow API modules
-  to be specified using a "module spec" array instead of a plain class name.
-  A "module spec" is an associative array containing at least the 'class' key
-  for the module's class, and optionally a 'factory' key for the factory function
-  to use for the module. This is intended for extensions that want control over
-  the instantiation of their API modules, to allow for proper dependency
-  injection.
 * Removed 'props' and 'errors' from action=paraminfo, as they have extremely
   limited use and are generally inaccurate, unmaintained, and impossible to
-  properly maintain. Also removed the corresponding methods from ApiBase and
-  the 'APIGetPossibleErrors' and 'APIGetResultProperties' hooks.
+  properly maintain.
 * Formats dbg, dump, txt, wddx, and yaml are now deprecated.
 * action=paraminfo now indicates when a parameter is specifying a submodule.
-  Internally, a new param type 'submodule' is available to indicate this which
-  automatically queries the list of submodule names from the ApiModuleManager.
 * The iwurl parameter to prop=iwlinks is deprecated in favor of iwprop=url, for
   parallelism with prop=langlinks.
 * All tokens should be fetched from action=query&meta=tokens; all other methods
@@ -258,6 +247,73 @@ production.
   parameter for each module is documented in the action=help output and is
   returned from action=paraminfo.
 
+=== Action API internal changes in 1.24 ===
+* Methods for handling continuation are added to ApiResult, so actions other
+  than query that use generators can easily support continuation.
+* $wgAPIModules (and the related $wgAPIFormatModules, $wgAPIMetaModules,
+  $wgAPIPropModules, and $wgAPIListModules settings) now allow API modules
+  to be specified using a "module spec" array instead of a plain class name.
+  A "module spec" is an associative array containing at least the 'class' key
+  for the module's class, and optionally a 'factory' key for the factory function
+  to use for the module. This is intended for extensions that want control over
+  the instantiation of their API modules, to allow for proper dependency
+  injection.
+* A new param type 'submodule' is available. Parameters of this type will take
+  the list of valid values from the module's ApiModuleManager for the group
+  corresponding to the parameter name.
+* The 'APIGetPossibleErrors' and 'APIGetResultProperties' hooks are no longer used.
+* API token handling has been rewritten. Any API module using tokens will need
+  to be updated:
+  * ApiBase::needsToken now returns a token type instead of boolean true when a
+    token is needed. Returning true will throw an exception. See documentation
+    of that method for details.
+  * Information for the 'token' parameter is automatically set by ApiBase
+    getFinalParams and getFinalParamDescription.
+  * ApiBase::getTokenSalt has been removed.
+  * The hooks APIQueryInfoTokens, APIQueryRevisionsTokens,
+    APIQueryRecentChangesTokens, APIQueryUsersTokens, and
+    ApiTokensGetTokenTypes are deprecated, but are still called to support
+    backwards-compatible token access.
+* The following methods have been deprecated and may be removed in a future
+  release:
+  * ApiBase::getResultProperties
+  * ApiBase::getFinalResultProperties
+  * ApiBase::addTokenProperties
+  * ApiBase::getRequireOnlyOneParameterErrorMessages
+  * ApiBase::getRequireMaxOneParameterErrorMessages
+  * ApiBase::getRequireAtLeastOneParameterErrorMessages
+  * ApiBase::getTitleOrPageIdErrorMessage
+  * ApiBase::getPossibleErrors
+  * ApiBase::getFinalPossibleErrors
+  * ApiBase::parseErrors
+  * ApiQuery::setGeneratorContinue
+  * ApiQueryInfo::getTokenFunctions
+  * ApiQueryInfo::resetTokenCache
+  * ApiQueryInfo::getEditToken
+  * ApiQueryInfo::getDeleteToken
+  * ApiQueryInfo::getProtectToken
+  * ApiQueryInfo::getMoveToken
+  * ApiQueryInfo::getBlockToken
+  * ApiQueryInfo::getUnblockToken
+  * ApiQueryInfo::getEmailToken
+  * ApiQueryInfo::getImportToken
+  * ApiQueryInfo::getWatchToken
+  * ApiQueryInfo::getOptionsToken
+  * ApiQueryRecentChanges::getTokenFunctions
+  * ApiQueryRecentChanges::getPatrolToken
+  * ApiQueryRevisions::getTokenFunctions
+  * ApiQueryRevisions::getRollbackToken
+  * ApiQueryUsers::getTokenFunctions
+  * ApiQueryUsers::getUserrightsToken
+* The following classes have been deprecated and may be removed in a future
+  release:
+  * ApiFormatDbg
+  * ApiFormatDump
+  * ApiFormatTxt
+  * ApiFormatWddx
+  * ApiFormatYaml
+  * ApiTokens
+
 === Languages updated in 1.24 ===
 
 MediaWiki supports over 350 languages. Many localisations are updated
index 61ed18f..5ec518b 100644 (file)
@@ -26,6 +26,7 @@
 
 /**
  * API PHP's var_export() output formatter
+ * @deprecated since 1.24
  * @ingroup API
  */
 class ApiFormatDbg extends ApiFormatBase {
index 7d32246..d4c7cab 100644 (file)
@@ -26,6 +26,7 @@
 
 /**
  * API PHP's var_dump() output formatter
+ * @deprecated since 1.24
  * @ingroup API
  */
 class ApiFormatDump extends ApiFormatBase {
index 3de2943..c451ed7 100644 (file)
@@ -26,6 +26,7 @@
 
 /**
  * API Text output formatter
+ * @deprecated since 1.24
  * @ingroup API
  */
 class ApiFormatTxt extends ApiFormatBase {
index a08c3ab..ba90c26 100644 (file)
@@ -26,6 +26,7 @@
 
 /**
  * API WDDX output formatter
+ * @deprecated since 1.24
  * @ingroup API
  */
 class ApiFormatWddx extends ApiFormatBase {
index 9f9b057..3798f89 100644 (file)
@@ -26,6 +26,7 @@
 
 /**
  * API YAML output formatter
+ * @deprecated since 1.24
  * @ingroup API
  */
 class ApiFormatYaml extends ApiFormatJson {