Merge commit 'f6d65'

# Conflicts:
#	skins/ArchLinux/ArchLinux.php

1 files changed, 349 insertions, 192 deletions

diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php
index 119d7b48..3bf066cf 100644
--- a/includes/api/ApiMain.php
+++ b/includes/api/ApiMain.php
@@ -42,7 +42,7 @@ class ApiMain extends ApiBase {
 	/**
 	 * When no format parameter is given, this format will be used
 	 */
-	const API_DEFAULT_FORMAT = 'xmlfm';
+	const API_DEFAULT_FORMAT = 'jsonfm';
 
 	/**
 	 * List of available modules: action name => module class
@@ -54,6 +54,7 @@ class ApiMain extends ApiBase {
 		'query' => 'ApiQuery',
 		'expandtemplates' => 'ApiExpandTemplates',
 		'parse' => 'ApiParse',
+		'stashedit' => 'ApiStashEdit',
 		'opensearch' => 'ApiOpenSearch',
 		'feedcontributions' => 'ApiFeedContributions',
 		'feedrecentchanges' => 'ApiFeedRecentChanges',
@@ -63,6 +64,7 @@ class ApiMain extends ApiBase {
 		'rsd' => 'ApiRsd',
 		'compare' => 'ApiComparePages',
 		'tokens' => 'ApiTokens',
+		'checktoken' => 'ApiCheckToken',
 
 		// Write modules
 		'purge' => 'ApiPurge',
@@ -86,6 +88,8 @@ class ApiMain extends ApiBase {
 		'options' => 'ApiOptions',
 		'imagerotate' => 'ApiImageRotate',
 		'revisiondelete' => 'ApiRevisionDelete',
+		'managetags' => 'ApiManageTags',
+		'tag' => 'ApiTag',
 	);
 
 	/**
@@ -121,11 +125,11 @@ class ApiMain extends ApiBase {
 	 */
 	private static $mRights = array(
 		'writeapi' => array(
-			'msg' => 'Use of the write API',
+			'msg' => 'right-writeapi',
 			'params' => array()
 		),
 		'apihighlimits' => array(
-			'msg' => 'Use higher limits in API queries (Slow queries: $1 results; Fast queries: $2 results). The limits for slow queries also apply to multivalue parameters.',
+			'msg' => 'api-help-right-apihighlimits',
 			'params' => array( ApiBase::LIMIT_SML2, ApiBase::LIMIT_BIG2 )
 		)
 	);
@@ -136,7 +140,7 @@ class ApiMain extends ApiBase {
 	 */
 	private $mPrinter;
 
-	private $mModuleMgr, $mResult;
+	private $mModuleMgr, $mResult, $mErrorFormatter, $mContinuationManager;
 	private $mAction;
 	private $mEnableWrite;
 	private $mInternalMode, $mSquidMaxage, $mModule;
@@ -178,15 +182,33 @@ class ApiMain extends ApiBase {
 			// Remove all modules other than login
 			global $wgUser;
 
-			if ( $this->getVal( 'callback' ) !== null ) {
-				// JSON callback allows cross-site reads.
-				// For safety, strip user credentials.
-				wfDebug( "API: stripping user credentials for JSON callback\n" );
+			if ( $this->lacksSameOriginSecurity() ) {
+				// If we're in a mode that breaks the same-origin policy, strip
+				// user credentials for security.
+				wfDebug( "API: stripping user credentials when the same-origin policy is not applied\n" );
 				$wgUser = new User();
 				$this->getContext()->setUser( $wgUser );
 			}
 		}
 
+		$uselang = $this->getParameter( 'uselang' );
+		if ( $uselang === 'user' ) {
+			// Assume the parent context is going to return the user language
+			// for uselang=user (see T85635).
+		} else {
+			if ( $uselang === 'content' ) {
+				global $wgContLang;
+				$uselang = $wgContLang->getCode();
+			}
+			$code = RequestContext::sanitizeLangCode( $uselang );
+			$this->getContext()->setLanguage( $code );
+			if ( !$this->mInternalMode ) {
+				global $wgLang;
+				$wgLang = $this->getContext()->getLanguage();
+				RequestContext::getMain()->setLanguage( $wgLang );
+			}
+		}
+
 		$config = $this->getConfig();
 		$this->mModuleMgr = new ApiModuleManager( $this );
 		$this->mModuleMgr->addModules( self::$Modules, 'action' );
@@ -194,7 +216,13 @@ class ApiMain extends ApiBase {
 		$this->mModuleMgr->addModules( self::$Formats, 'format' );
 		$this->mModuleMgr->addModules( $config->get( 'APIFormatModules' ), 'format' );
 
-		$this->mResult = new ApiResult( $this );
+		Hooks::run( 'ApiMain::moduleManager', array( $this->mModuleMgr ) );
+
+		$this->mResult = new ApiResult( $this->getConfig()->get( 'APIMaxResultSize' ) );
+		$this->mErrorFormatter = new ApiErrorFormatter_BackCompat( $this->mResult );
+		$this->mResult->setErrorFormatter( $this->mErrorFormatter );
+		$this->mResult->setMainForContinuation( $this );
+		$this->mContinuationManager = null;
 		$this->mEnableWrite = $enableWrite;
 
 		$this->mSquidMaxage = -1; // flag for executeActionWithErrorHandling()
@@ -219,6 +247,43 @@ class ApiMain extends ApiBase {
 	}
 
 	/**
+	 * Get the ApiErrorFormatter object associated with current request
+	 * @return ApiErrorFormatter
+	 */
+	public function getErrorFormatter() {
+		return $this->mErrorFormatter;
+	}
+
+	/**
+	 * Get the continuation manager
+	 * @return ApiContinuationManager|null
+	 */
+	public function getContinuationManager() {
+		return $this->mContinuationManager;
+	}
+
+	/**
+	 * Set the continuation manager
+	 * @param ApiContinuationManager|null
+	 */
+	public function setContinuationManager( $manager ) {
+		if ( $manager !== null ) {
+			if ( !$manager instanceof ApiContinuationManager ) {
+				throw new InvalidArgumentException( __METHOD__ . ': Was passed ' .
+					is_object( $manager ) ? get_class( $manager ) : gettype( $manager )
+				);
+			}
+			if ( $this->mContinuationManager !== null ) {
+				throw new UnexpectedValueException(
+					__METHOD__ . ': tried to set manager from ' . $manager->getSource() .
+					' when a manager is already set from ' . $this->mContinuationManager->getSource()
+				);
+			}
+		}
+		$this->mContinuationManager = $manager;
+	}
+
+	/**
 	 * Get the API module object. Only works after executeAction()
 	 *
 	 * @return ApiBase
@@ -290,6 +355,16 @@ class ApiMain extends ApiBase {
 			}
 		}
 
+		if ( $mode === 'public' && $this->getParameter( 'uselang' ) === 'user' ) {
+			// User language is used for i18n, so we don't want to publicly
+			// cache. Anons are ok, because if they have non-default language
+			// then there's an appropriate Vary header set by whatever set
+			// their non-default language.
+			wfDebug( __METHOD__ . ": downgrading cache mode 'public' to " .
+				"'anon-public-user-private' due to uselang=user\n" );
+			$mode = 'anon-public-user-private';
+		}
+
 		wfDebug( __METHOD__ . ": setting cache mode $mode\n" );
 		$this->mCacheMode = $mode;
 	}
@@ -328,14 +403,11 @@ class ApiMain extends ApiBase {
 	 * Execute api request. Any errors will be handled if the API was called by the remote client.
 	 */
 	public function execute() {
-		$this->profileIn();
 		if ( $this->mInternalMode ) {
 			$this->executeAction();
 		} else {
 			$this->executeActionWithErrorHandling();
 		}
-
-		$this->profileOut();
 	}
 
 	/**
@@ -373,10 +445,6 @@ class ApiMain extends ApiBase {
 		// avoid sending public cache headers for errors.
 		$this->sendCacheHeaders();
 
-		if ( $this->mPrinter->getIsHtml() && !$this->mPrinter->isDisabled() ) {
-			echo wfReportTime();
-		}
-
 		ob_end_flush();
 	}
 
@@ -390,11 +458,17 @@ class ApiMain extends ApiBase {
 		// Bug 63145: Rollback any open database transactions
 		if ( !( $e instanceof UsageException ) ) {
 			// UsageExceptions are intentional, so don't rollback if that's the case
-			MWExceptionHandler::rollbackMasterChangesAndLog( $e );
+			try {
+				MWExceptionHandler::rollbackMasterChangesAndLog( $e );
+			} catch ( DBError $e2 ) {
+				// Rollback threw an exception too. Log it, but don't interrupt
+				// our regularly scheduled exception handling.
+				MWExceptionHandler::logException( $e2 );
+			}
 		}
 
 		// Allow extra cleanup and logging
-		wfRunHooks( 'ApiMain::onException', array( $this, $e ) );
+		Hooks::run( 'ApiMain::onException', array( $this, $e ) );
 
 		// Log it
 		if ( !( $e instanceof UsageException ) ) {
@@ -421,9 +495,22 @@ class ApiMain extends ApiBase {
 		// Reset and print just the error message
 		ob_clean();
 
-		// If the error occurred during printing, do a printer->profileOut()
-		$this->mPrinter->safeProfileOut();
-		$this->printResult( true );
+		// Printer may not be initialized if the extractRequestParams() fails for the main module
+		$this->createErrorPrinter();
+
+		try {
+			$this->printResult( true );
+		} catch ( UsageException $ex ) {
+			// The error printer itself is failing. Try suppressing its request
+			// parameters and redo.
+			$this->setWarning(
+				'Error printer failed (will retry without params): ' . $ex->getMessage()
+			);
+			$this->mPrinter = null;
+			$this->createErrorPrinter();
+			$this->mPrinter->forceDefaultParams();
+			$this->printResult( true );
+		}
 	}
 
 	/**
@@ -434,6 +521,7 @@ class ApiMain extends ApiBase {
 	 *
 	 * @since 1.23
 	 * @param Exception $e
+	 * @throws Exception
 	 */
 	public static function handleApiBeforeMainException( Exception $e ) {
 		ob_start();
@@ -462,6 +550,8 @@ class ApiMain extends ApiBase {
 	 * If the parameter and the header do match, the header is checked against $wgCrossSiteAJAXdomains
 	 * and $wgCrossSiteAJAXdomainExceptions, and if the origin qualifies, the appropriate CORS
 	 * headers are set.
+	 * http://www.w3.org/TR/cors/#resource-requests
+	 * http://www.w3.org/TR/cors/#resource-preflight-requests
 	 *
 	 * @return bool False if the caller should abort (403 case), true otherwise (all other cases)
 	 */
@@ -474,12 +564,14 @@ class ApiMain extends ApiBase {
 
 		$request = $this->getRequest();
 		$response = $request->response();
+
 		// Origin: header is a space-separated list of origins, check all of them
 		$originHeader = $request->getHeader( 'Origin' );
 		if ( $originHeader === false ) {
 			$origins = array();
 		} else {
-			$origins = explode( ' ', $originHeader );
+			$originHeader = trim( $originHeader );
+			$origins = preg_split( '/\s+/', $originHeader );
 		}
 
 		if ( !in_array( $originParam, $origins ) ) {
@@ -494,18 +586,44 @@ class ApiMain extends ApiBase {
 		}
 
 		$config = $this->getConfig();
-		$matchOrigin = self::matchOrigin(
+		$matchOrigin = count( $origins ) === 1 && self::matchOrigin(
 			$originParam,
 			$config->get( 'CrossSiteAJAXdomains' ),
 			$config->get( 'CrossSiteAJAXdomainExceptions' )
 		);
 
 		if ( $matchOrigin ) {
-			$response->header( "Access-Control-Allow-Origin: $originParam" );
+			$requestedMethod = $request->getHeader( 'Access-Control-Request-Method' );
+			$preflight = $request->getMethod() === 'OPTIONS' && $requestedMethod !== false;
+			if ( $preflight ) {
+				// This is a CORS preflight request
+				if ( $requestedMethod !== 'POST' && $requestedMethod !== 'GET' ) {
+					// If method is not a case-sensitive match, do not set any additional headers and terminate.
+					return true;
+				}
+				// We allow the actual request to send the following headers
+				$requestedHeaders = $request->getHeader( 'Access-Control-Request-Headers' );
+				if ( $requestedHeaders !== false ) {
+					if ( !self::matchRequestedHeaders( $requestedHeaders ) ) {
+						return true;
+					}
+					$response->header( 'Access-Control-Allow-Headers: ' . $requestedHeaders );
+				}
+
+				// We only allow the actual request to be GET or POST
+				$response->header( 'Access-Control-Allow-Methods: POST, GET' );
+			}
+
+			$response->header( "Access-Control-Allow-Origin: $originHeader" );
 			$response->header( 'Access-Control-Allow-Credentials: true' );
-			$this->getOutput()->addVaryHeader( 'Origin' );
+			$response->header( "Timing-Allow-Origin: $originHeader" ); # http://www.w3.org/TR/resource-timing/#timing-allow-origin
+
+			if ( !$preflight ) {
+				$response->header( 'Access-Control-Expose-Headers: MediaWiki-API-Error, Retry-After, X-Database-Lag' );
+			}
 		}
 
+		$this->getOutput()->addVaryHeader( 'Origin' );
 		return true;
 	}
 
@@ -535,6 +653,41 @@ class ApiMain extends ApiBase {
 	}
 
 	/**
+	 * Attempt to validate the value of Access-Control-Request-Headers against a list
+	 * of headers that we allow the follow up request to send.
+	 *
+	 * @param string $requestedHeaders Comma seperated list of HTTP headers
+	 * @return bool True if all requested headers are in the list of allowed headers
+	 */
+	protected static function matchRequestedHeaders( $requestedHeaders ) {
+		if ( trim( $requestedHeaders ) === '' ) {
+			return true;
+		}
+		$requestedHeaders = explode( ',', $requestedHeaders );
+		$allowedAuthorHeaders = array_flip( array(
+			/* simple headers (see spec) */
+			'accept',
+			'accept-language',
+			'content-language',
+			'content-type',
+			/* non-authorable headers in XHR, which are however requested by some UAs */
+			'accept-encoding',
+			'dnt',
+			'origin',
+			/* MediaWiki whitelist */
+			'api-user-agent',
+		) );
+		foreach ( $requestedHeaders as $rHeader ) {
+			$rHeader = strtolower( trim( $rHeader ) );
+			if ( !isset( $allowedAuthorHeaders[$rHeader] ) ) {
+				wfDebugLog( 'api', 'CORS preflight failed on requested header: ' . $rHeader );
+				return false;
+			}
+		}
+		return true;
+	}
+
+	/**
 	 * Helper function to convert wildcard string into a regex
 	 * '*' => '.*?'
 	 * '?' => '.'
@@ -563,8 +716,24 @@ class ApiMain extends ApiBase {
 			$out->addVaryHeader( 'X-Forwarded-Proto' );
 		}
 
+		// The logic should be:
+		// $this->mCacheControl['max-age'] is set?
+		//    Use it, the module knows better than our guess.
+		// !$this->mModule || $this->mModule->isWriteMode(), and mCacheMode is private?
+		//    Use 0 because we can guess caching is probably the wrong thing to do.
+		// Use $this->getParameter( 'maxage' ), which already defaults to 0.
+		$maxage = 0;
+		if ( isset( $this->mCacheControl['max-age'] ) ) {
+			$maxage = $this->mCacheControl['max-age'];
+		} elseif ( ( $this->mModule && !$this->mModule->isWriteMode() ) ||
+			$this->mCacheMode !== 'private'
+		) {
+			$maxage = $this->getParameter( 'maxage' );
+		}
+		$privateCache = 'private, must-revalidate, max-age=' . $maxage;
+
 		if ( $this->mCacheMode == 'private' ) {
-			$response->header( 'Cache-Control: private' );
+			$response->header( "Cache-Control: $privateCache" );
 			return;
 		}
 
@@ -576,14 +745,14 @@ class ApiMain extends ApiBase {
 				$response->header( $out->getXVO() );
 				if ( $out->haveCacheVaryCookies() ) {
 					// Logged in, mark this request private
-					$response->header( 'Cache-Control: private' );
+					$response->header( "Cache-Control: $privateCache" );
 					return;
 				}
 				// Logged out, send normal public headers below
 			} elseif ( session_id() != '' ) {
 				// Logged in or otherwise has session (e.g. anonymous users who have edited)
 				// Mark request private
-				$response->header( 'Cache-Control: private' );
+				$response->header( "Cache-Control: $privateCache" );
 
 				return;
 			} // else no XVO and anonymous, send public headers below
@@ -607,7 +776,7 @@ class ApiMain extends ApiBase {
 			// Public cache not requested
 			// Sending a Vary header in this case is harmless, and protects us
 			// against conditional calls of setCacheMaxAge().
-			$response->header( 'Cache-Control: private' );
+			$response->header( "Cache-Control: $privateCache" );
 
 			return;
 		}
@@ -638,45 +807,39 @@ class ApiMain extends ApiBase {
 	}
 
 	/**
-	 * Replace the result data with the information about an exception.
-	 * Returns the error code
-	 * @param Exception $e
-	 * @return string
+	 * Create the printer for error output
 	 */
-	protected function substituteResultWithError( $e ) {
-		$result = $this->getResult();
-
-		// Printer may not be initialized if the extractRequestParams() fails for the main module
+	private function createErrorPrinter() {
 		if ( !isset( $this->mPrinter ) ) {
-			// The printer has not been created yet. Try to manually get formatter value.
 			$value = $this->getRequest()->getVal( 'format', self::API_DEFAULT_FORMAT );
 			if ( !$this->mModuleMgr->isDefined( $value, 'format' ) ) {
 				$value = self::API_DEFAULT_FORMAT;
 			}
-
 			$this->mPrinter = $this->createPrinterByName( $value );
 		}
 
 		// Printer may not be able to handle errors. This is particularly
 		// likely if the module returns something for getCustomPrinter().
 		if ( !$this->mPrinter->canPrintErrors() ) {
-			$this->mPrinter->safeProfileOut();
 			$this->mPrinter = $this->createPrinterByName( self::API_DEFAULT_FORMAT );
 		}
+	}
 
-		// Update raw mode flag for the selected printer.
-		$result->setRawMode( $this->mPrinter->getNeedsRawData() );
-
+	/**
+	 * Replace the result data with the information about an exception.
+	 * Returns the error code
+	 * @param Exception $e
+	 * @return string
+	 */
+	protected function substituteResultWithError( $e ) {
+		$result = $this->getResult();
 		$config = $this->getConfig();
 
 		if ( $e instanceof UsageException ) {
-			// User entered incorrect parameters - print usage screen
+			// User entered incorrect parameters - generate error response
 			$errMessage = $e->getMessageArray();
-
-			// Only print the help message when this is for the developer, not runtime
-			if ( $this->mPrinter->getWantsHelp() || $this->mAction == 'help' ) {
-				ApiResult::setContent( $errMessage, $this->makeHelpMsg() );
-			}
+			$link = wfExpandUrl( wfScript( 'api' ) );
+			ApiResult::setContentValue( $errMessage, 'docref', "See $link for API usage" );
 		} else {
 			// Something is seriously wrong
 			if ( ( $e instanceof DBQueryError ) && !$config->get( 'ShowSQLErrors' ) ) {
@@ -687,17 +850,19 @@ class ApiMain extends ApiBase {
 
 			$errMessage = array(
 				'code' => 'internal_api_error_' . get_class( $e ),
-				'info' => $info,
-			);
-			ApiResult::setContent(
-				$errMessage,
-				$config->get( 'ShowExceptionDetails' ) ? "\n\n{$e->getTraceAsString()}\n\n" : ''
+				'info' => '[' . MWExceptionHandler::getLogId( $e ) . '] ' . $info,
 			);
+			if ( $config->get( 'ShowExceptionDetails' ) ) {
+				ApiResult::setContentValue(
+					$errMessage,
+					'trace',
+					MWExceptionHandler::getRedactedTraceAsString( $e )
+				);
+			}
 		}
 
 		// Remember all the warnings to re-add them later
-		$oldResult = $result->getData();
-		$warnings = isset( $oldResult['warnings'] ) ? $oldResult['warnings'] : null;
+		$warnings = $result->getResultData( array( 'warnings' ) );
 
 		$result->reset();
 		// Re-add the id
@@ -756,6 +921,8 @@ class ApiMain extends ApiBase {
 	/**
 	 * Set up the module for response
 	 * @return ApiBase The module that will handle this action
+	 * @throws MWException
+	 * @throws UsageException
 	 */
 	protected function setupModule() {
 		// Instantiate the module requested by the user
@@ -856,7 +1023,7 @@ class ApiMain extends ApiBase {
 
 		// Allow extensions to stop execution for arbitrary reasons.
 		$message = false;
-		if ( !wfRunHooks( 'ApiCheckCanExecute', array( $module, $user, &$message ) ) ) {
+		if ( !Hooks::run( 'ApiCheckCanExecute', array( $module, $user, &$message ) ) ) {
 			$this->dieUsageMsg( $message );
 		}
 	}
@@ -928,10 +1095,8 @@ class ApiMain extends ApiBase {
 		$this->checkAsserts( $params );
 
 		// Execute
-		$module->profileIn();
 		$module->execute();
-		wfRunHooks( 'APIAfterExecute', array( &$module ) );
-		$module->profileOut();
+		Hooks::run( 'APIAfterExecute', array( &$module ) );
 
 		$this->reportUnusedParams();
 
@@ -1080,23 +1245,10 @@ class ApiMain extends ApiBase {
 			$this->setWarning( 'SECURITY WARNING: $wgDebugAPI is enabled' );
 		}
 
-		$this->getResult()->cleanUpUTF8();
 		$printer = $this->mPrinter;
-		$printer->profileIn();
-
-		/**
-		 * If the help message is requested in the default (xmlfm) format,
-		 * tell the printer not to escape ampersands so that our links do
-		 * not break.
-		 */
-		$isHelp = $isError || $this->mAction == 'help';
-		$printer->setUnescapeAmps( $isHelp && $printer->getFormat() == 'XML' && $printer->getIsHtml() );
-
-		$printer->initPrinter( $isHelp );
-
+		$printer->initPrinter( false );
 		$printer->execute();
 		$printer->closePrinter();
-		$printer->profileOut();
 	}
 
 	/**
@@ -1113,14 +1265,14 @@ class ApiMain extends ApiBase {
 	 */
 	public function getAllowedParams() {
 		return array(
-			'format' => array(
-				ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
-				ApiBase::PARAM_TYPE => 'submodule',
-			),
 			'action' => array(
 				ApiBase::PARAM_DFLT => 'help',
 				ApiBase::PARAM_TYPE => 'submodule',
 			),
+			'format' => array(
+				ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
+				ApiBase::PARAM_TYPE => 'submodule',
+			),
 			'maxlag' => array(
 				ApiBase::PARAM_TYPE => 'integer'
 			),
@@ -1139,126 +1291,136 @@ class ApiMain extends ApiBase {
 			'servedby' => false,
 			'curtimestamp' => false,
 			'origin' => null,
+			'uselang' => array(
+				ApiBase::PARAM_DFLT => 'user',
+			),
 		);
 	}
 
-	/**
-	 * See ApiBase for description.
-	 *
-	 * @return array
-	 */
-	public function getParamDescription() {
+	/** @see ApiBase::getExamplesMessages() */
+	protected function getExamplesMessages() {
 		return array(
-			'format' => 'The format of the output',
-			'action' => 'What action you would like to perform. See below for module help',
-			'maxlag' => array(
-				'Maximum lag can be used when MediaWiki is installed on a database replicated cluster.',
-				'To save actions causing any more site replication lag, this parameter can make the client',
-				'wait until the replication lag is less than the specified value.',
-				'In case of a replag error, error code "maxlag" is returned, with the message like',
-				'"Waiting for $host: $lag seconds lagged\n".',
-				'See https://www.mediawiki.org/wiki/Manual:Maxlag_parameter for more information',
-			),
-			'smaxage' => 'Set the s-maxage header to this many seconds. Errors are never cached',
-			'maxage' => 'Set the max-age header to this many seconds. Errors are never cached',
-			'assert' => 'Verify the user is logged in if set to "user", or has the bot userright if "bot"',
-			'requestid' => 'Request ID to distinguish requests. This will just be output back to you',
-			'servedby' => 'Include the hostname that served the request in the ' .
-				'results. Unconditionally shown on error',
-			'curtimestamp' => 'Include the current timestamp in the result.',
-			'origin' => array(
-				'When accessing the API using a cross-domain AJAX request (CORS), set this to the',
-				'originating domain. This must be included in any pre-flight request, and',
-				'therefore must be part of the request URI (not the POST body). This must match',
-				'one of the origins in the Origin: header exactly, so it has to be set to ',
-				'something like http://en.wikipedia.org or https://meta.wikimedia.org . If this',
-				'parameter does not match the Origin: header, a 403 response will be returned. If',
-				'this parameter matches the Origin: header and the origin is whitelisted, an',
-				'Access-Control-Allow-Origin header will be set.',
-			),
+			'action=help'
+				=> 'apihelp-help-example-main',
+			'action=help&recursivesubmodules=1'
+				=> 'apihelp-help-example-recursive',
 		);
 	}
 
+	public function modifyHelp( array &$help, array $options ) {
+		// Wish PHP had an "array_insert_before". Instead, we have to manually
+		// reindex the array to get 'permissions' in the right place.
+		$oldHelp = $help;
+		$help = array();
+		foreach ( $oldHelp as $k => $v ) {
+			if ( $k === 'submodules' ) {
+				$help['permissions'] = '';
+			}
+			$help[$k] = $v;
+		}
+		$help['credits'] = '';
+
+		// Fill 'permissions'
+		$help['permissions'] .= Html::openElement( 'div',
+			array( 'class' => 'apihelp-block apihelp-permissions' ) );
+		$m = $this->msg( 'api-help-permissions' );
+		if ( !$m->isDisabled() ) {
+			$help['permissions'] .= Html::rawElement( 'div', array( 'class' => 'apihelp-block-head' ),
+				$m->numParams( count( self::$mRights ) )->parse()
+			);
+		}
+		$help['permissions'] .= Html::openElement( 'dl' );
+		foreach ( self::$mRights as $right => $rightMsg ) {
+			$help['permissions'] .= Html::element( 'dt', null, $right );
+
+			$rightMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )->parse();
+			$help['permissions'] .= Html::rawElement( 'dd', null, $rightMsg );
+
+			$groups = array_map( function ( $group ) {
+				return $group == '*' ? 'all' : $group;
+			}, User::getGroupsWithPermission( $right ) );
+
+			$help['permissions'] .= Html::rawElement( 'dd', null,
+				$this->msg( 'api-help-permissions-granted-to' )
+					->numParams( count( $groups ) )
+					->params( $this->getLanguage()->commaList( $groups ) )
+					->parse()
+			);
+		}
+		$help['permissions'] .= Html::closeElement( 'dl' );
+		$help['permissions'] .= Html::closeElement( 'div' );
+
+		// Fill 'credits', if applicable
+		if ( empty( $options['nolead'] ) ) {
+			$help['credits'] .= Html::element( 'h' . min( 6, $options['headerlevel'] + 1 ),
+				array( 'id' => '+credits', 'class' => 'apihelp-header' ),
+				$this->msg( 'api-credits-header' )->parse()
+			);
+			$help['credits'] .= $this->msg( 'api-credits' )->useDatabase( false )->parseAsBlock();
+		}
+	}
+
+	private $mCanApiHighLimits = null;
+
 	/**
-	 * See ApiBase for description.
-	 *
-	 * @return array
+	 * Check whether the current user is allowed to use high limits
+	 * @return bool
 	 */
-	public function getDescription() {
-		return array(
-			'',
-			'',
-			'**********************************************************************************************',
-			'**                                                                                          **',
-			'**                This is an auto-generated MediaWiki API documentation page                **',
-			'**                                                                                          **',
-			'**                               Documentation and Examples:                                **',
-			'**                            https://www.mediawiki.org/wiki/API                            **',
-			'**                                                                                          **',
-			'**********************************************************************************************',
-			'',
-			'Status:                All features shown on this page should be working, but the API',
-			'                       is still in active development, and may change at any time.',
-			'                       Make sure to monitor our mailing list for any updates.',
-			'',
-			'Erroneous requests:    When erroneous requests are sent to the API, a HTTP header will be sent',
-			'                       with the key "MediaWiki-API-Error" and then both the value of the',
-			'                       header and the error code sent back will be set to the same value.',
-			'',
-			'                       In the case of an invalid action being passed, these will have a value',
-			'                       of "unknown_action".',
-			'',
-			'                       For more information see https://www.mediawiki.org' .
-				'/wiki/API:Errors_and_warnings',
-			'',
-			'Documentation:         https://www.mediawiki.org/wiki/API:Main_page',
-			'FAQ                    https://www.mediawiki.org/wiki/API:FAQ',
-			'Mailing list:          https://lists.wikimedia.org/mailman/listinfo/mediawiki-api',
-			'Api Announcements:     https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce',
-			'Bugs & Requests:       https://bugzilla.wikimedia.org/buglist.cgi?component=API&' .
-				'bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&order=bugs.delta_ts',
-			'',
-			'',
-			'',
-			'',
-			'',
-		);
+	public function canApiHighLimits() {
+		if ( !isset( $this->mCanApiHighLimits ) ) {
+			$this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
+		}
+
+		return $this->mCanApiHighLimits;
 	}
 
 	/**
-	 * Returns an array of strings with credits for the API
-	 * @return array
+	 * Overrides to return this instance's module manager.
+	 * @return ApiModuleManager
 	 */
-	protected function getCredits() {
-		return array(
-			'API developers:',
-			'    Roan Kattouw (lead developer Sep 2007-2009)',
-			'    Victor Vasiliev',
-			'    Bryan Tong Minh',
-			'    Sam Reed',
-			'    Yuri Astrakhan (creator, lead developer Sep 2006-Sep 2007, 2012-2013)',
-			'    Brad Jorsch (lead developer 2013-now)',
-			'',
-			'Please send your comments, suggestions and questions to mediawiki-api@lists.wikimedia.org',
-			'or file a bug report at https://bugzilla.wikimedia.org/'
+	public function getModuleManager() {
+		return $this->mModuleMgr;
+	}
+
+	/**
+	 * Fetches the user agent used for this request
+	 *
+	 * The value will be the combination of the 'Api-User-Agent' header (if
+	 * any) and the standard User-Agent header (if any).
+	 *
+	 * @return string
+	 */
+	public function getUserAgent() {
+		return trim(
+			$this->getRequest()->getHeader( 'Api-user-agent' ) . ' ' .
+			$this->getRequest()->getHeader( 'User-agent' )
 		);
 	}
 
+	/************************************************************************//**
+	 * @name   Deprecated
+	 * @{
+	 */
+
 	/**
 	 * Sets whether the pretty-printer should format *bold* and $italics$
 	 *
+	 * @deprecated since 1.25
 	 * @param bool $help
 	 */
 	public function setHelp( $help = true ) {
+		wfDeprecated( __METHOD__, '1.25' );
 		$this->mPrinter->setHelp( $help );
 	}
 
 	/**
 	 * Override the parent to generate help messages for all available modules.
 	 *
+	 * @deprecated since 1.25
 	 * @return string
 	 */
 	public function makeHelpMsg() {
+		wfDeprecated( __METHOD__, '1.25' );
 		global $wgMemc;
 		$this->setHelp();
 		// Get help text from cache if present
@@ -1281,9 +1443,11 @@ class ApiMain extends ApiBase {
 	}
 
 	/**
+	 * @deprecated since 1.25
 	 * @return mixed|string
 	 */
 	public function reallyMakeHelpMsg() {
+		wfDeprecated( __METHOD__, '1.25' );
 		$this->setHelp();
 
 		// Use parent to make default message for the main module
@@ -1305,8 +1469,12 @@ class ApiMain extends ApiBase {
 
 		$msg .= "\n$astriks Permissions $astriks\n\n";
 		foreach ( self::$mRights as $right => $rightMsg ) {
+			$rightsMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )
+				->useDatabase( false )
+				->inLanguage( 'en' )
+				->text();
 			$groups = User::getGroupsWithPermission( $right );
-			$msg .= "* " . $right . " *\n  " . wfMsgReplaceArgs( $rightMsg['msg'], $rightMsg['params'] ) .
+			$msg .= "* " . $right . " *\n  $rightsMsg" .
 				"\nGranted to:\n  " . str_replace( '*', 'all', implode( ', ', $groups ) ) . "\n\n";
 		}
 
@@ -1321,18 +1489,22 @@ class ApiMain extends ApiBase {
 			$msg .= "\n";
 		}
 
-		$msg .= "\n*** Credits: ***\n   " . implode( "\n   ", $this->getCredits() ) . "\n";
+		$credits = $this->msg( 'api-credits' )->useDatabase( 'false' )->inLanguage( 'en' )->text();
+		$credits = str_replace( "\n", "\n   ", $credits );
+		$msg .= "\n*** Credits: ***\n   $credits\n";
 
 		return $msg;
 	}
 
 	/**
+	 * @deprecated since 1.25
 	 * @param ApiBase $module
 	 * @param string $paramName What type of request is this? e.g. action,
 	 *    query, list, prop, meta, format
 	 * @return string
 	 */
 	public static function makeHelpMsgHeader( $module, $paramName ) {
+		wfDeprecated( __METHOD__, '1.25' );
 		$modulePrefix = $module->getModulePrefix();
 		if ( strval( $modulePrefix ) !== '' ) {
 			$modulePrefix = "($modulePrefix) ";
@@ -1341,20 +1513,6 @@ class ApiMain extends ApiBase {
 		return "* $paramName={$module->getModuleName()} $modulePrefix*";
 	}
 
-	private $mCanApiHighLimits = null;
-
-	/**
-	 * Check whether the current user is allowed to use high limits
-	 * @return bool
-	 */
-	public function canApiHighLimits() {
-		if ( !isset( $this->mCanApiHighLimits ) ) {
-			$this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
-		}
-
-		return $this->mCanApiHighLimits;
-	}
-
 	/**
 	 * Check whether the user wants us to show version information in the API help
 	 * @return bool
@@ -1367,14 +1525,6 @@ class ApiMain extends ApiBase {
 	}
 
 	/**
-	 * Overrides to return this instance's module manager.
-	 * @return ApiModuleManager
-	 */
-	public function getModuleManager() {
-		return $this->mModuleMgr;
-	}
-
-	/**
 	 * Add or overwrite a module in this ApiMain instance. Intended for use by extending
 	 * classes who wish to add their own modules to their lexicon or override the
 	 * behavior of inherent ones.
@@ -1418,11 +1568,13 @@ class ApiMain extends ApiBase {
 	public function getFormats() {
 		return $this->getModuleManager()->getNamesWithClasses( 'format' );
 	}
+
+	/**@}*/
+
 }
 
 /**
  * This exception will be thrown when dieUsage is called to stop module execution.
- * The exception handling code will print a help screen explaining how this API may be used.
  *
  * @ingroup API
  */
@@ -1476,3 +1628,8 @@ class UsageException extends MWException {
 		return "{$this->getCodeString()}: {$this->getMessage()}";
 	}
 }
+
+/**
+ * For really cool vim folding this needs to be at the end:
+ * vim: foldmarker=@{,@} foldmethod=marker
+ */