API:扩展

本文档介绍在扩展中创建API模块，以便与MediaWiki 1.30及更高版本一起使用。

模块创建与注册

所有API模块都是ApiBase 的子类，但某些类型的模块使用派生基类。 注册方法也取决于模块类型。

动作模块

为主action参数提供值的模块应子类ApiBase 。 它们应使用APIModules密钥在extension.json中注册。

格式模块

为format主参数提供值的模块应子类ApiFormatBase。 它们应使用APIFormatModules关键字在extension.json中注册。 扩展需要添加格式模块的情况并不多见。

查询子模块

为 action=query 提供 prop、list 或 meta 参数值的模块应子类为 ApiQueryBase（如果不能用作生成器）或 ApiQueryGeneratorBase（如果可以用作生成器）。 它们应使用 APIPropModules、APIListModules 或 APIMetaModules 关键字在 extension.json 中注册。

在所有情况下，注册密钥的值都是一个以模块名（即参数值）为键、以类名为值的对象。 也可以使用 ApiMain::moduleManager （用于动作和格式模块）和 ApiQuery::moduleManager （用于查询子模块）钩子有条件地注册模块。

实现

前缀

在 API 模块的构造函数中，当您调用 parent::__construct() 时，可以为模块参数指定一个可选前缀。 (在为模块生成的文档中，如果有前缀，该前缀会出现在模块标题的括号中)。 如果模块是查询子模块，则需要前缀，因为客户端可以在一个请求中调用多个子模块，每个子模块都有自己的参数。 对于动作和格式模块，前缀是可选的。

参数

Most modules require parameters. These are defined by implementing getAllowedParams(). The return value is an associative array where keys are the (unprefixed) parameter names and values are either the scalar default value for the parameter or an array defining the properties of the parameter using the PARAM_* constants defined by ApiBase.

The example illustrates the syntax and some of the more common PARAM_* constants.

	protected function getAllowedParams() {
		return [
			// An optional parameter with a default value
			'simple' => 'value',

			// 一个必需的参数
			'required' => [
				ApiBase::PARAM_TYPE => 'string',
				ApiBase::PARAM_REQUIRED => true,
			],

			// A parameter accepting multiple values from a list
			'variable' => [
				// The default set of values
				ApiBase::PARAM_DFLT => 'foo|bar|baz',
				// 所有可能的值
				ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
				// Indicate that multiple values are accepted
				ApiBase::PARAM_ISMULTI => true,
				// Use standard "per value" documentation messages
				ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
			],

			// A standard "limit" parameter. It's generally best not to vary from this standard.
			'limit' => [
				ApiBase::PARAM_DFLT => 10,
				ApiBase::PARAM_TYPE => 'limit',
				ApiBase::PARAM_MIN => 1,
				ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
				ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
			],
		];
	}

Parameters are documented using MediaWiki's i18n mechanism. See #Documentation for details.

Execution and output

The code actually implementing the module goes in the execute() method. This code will generally use $this→extractRequestParams() to get the input parameters, and will use $this→getResult() to get the ApiResult object to add any output to.

Query prop submodules should use $this→getPageSet() to access the set of pages to operate on.

Query submodules that can be used as generators will also need to implement executeGenerator() which is passed and ApiPageSet that should be filled with the generated pages. In this case, the ApiResult should generally not be used.

缓存

默认情况下 API 响应是不可缓存的('Cache-Control: private')！ For action modules, you can allow caching by calling $this→getMain()→setCacheMode(). This still requires clients pass the maxage or smaxage parameters to actually enable caching. You can force caching by also calling $this→getMain()→setCacheMaxAge().

For query modules, do not call those methods. You can allow caching by instead implementing getCacheMode().

In either case, be sure that private data is not exposed.

Token handling

If your action module changes the wiki in any way, it should require a token of some kind. To have this handled automatically, implement the needsToken() method, returning the token that your module requires (probably the 'csrf' edit token). The API base code will then automatically validate the token that clients provide in API requests in a token parameter.

If you don't want to use a token that is part of core, but rather a custom token with your own permission checks, use ApiQueryTokensRegisterTypes hook to register your token.

Primary database access

If your module accesses the primary database, it should implement the isWriteMode() method to return true.

返回错误

ApiBase includes several methods for performing various checks, for example,

• If you need to assert that exactly one of a set of parameters was supplied, use $this→requireOnlyOneParameter().

• If you need to assert that at most one of a set of parameters was supplied, use $this→requireMaxOneParameter().

• If you need to assert that at least one of a set of parameters was supplied, use $this→requireAtLeastOneParameter().

• If you need to assert that the user has certain rights, use $this→checkUserRightsAny().

• If you need to assert that the user can take an action on a particular page, use $this→checkTitleUserPermissions().

• If the user is blocked (and that matters to your module), pass the Block object to $this→dieBlocked().

But you will often run into cases where you need to raise an error of your own. The usual way to do that is to call $this→dieWithError(), although if you have a StatusValue with the error information you could pass it to $this→dieStatus() instead.

If you need to issue a warning rather than an error, use $this→addWarning() or $this→addDeprecation() if it's a deprecation warning.

帮助文档

The API is documented using MediaWiki's i18n mechanism. Needed messages generally have default names based on the module's "path". For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with query+.

Every module will need a apihelp-$path-summary message, which should be a one-line description of the module. If additional help text is needed, apihelp-$path-extended-description may be created as well. Each parameter will need a apihelp-$path-param-$name message, and parameters using PARAM_HELP_MSG_PER_VALUE will also need a apihelp-$path-paramvalue-$name-$value for each value.

More details on API documentation are available at API:本地化 .

Extensions may also document their extra API modules on mediawiki.org. This should be located on the extension's main page or, if more space is required, on pages named Extension:<ExtensionName>/API or subpages thereof (e.g. CentralAuth , MassMessage , or StructuredDiscussions ). The API namespace is reserved for the API of MediaWiki core.

拓展核心模块

从 MediaWiki 1.14 开始，可以使用下列钩子拓展和讯模块的功能：

• APIGetAllowedParams - to add or modify the module's parameter list
• APIGetParamDescriptionMessages - to add or modify the module's parameter descriptions
• APIAfterExecute - to do something after the module has been executed (but before the result has been output)

• • Use APIQueryAfterExecute for prop=, list= and meta= modules

• • • If the module is run in generator mode, APIQueryGeneratorAfterExecute will be called instead

具有API功能的扩展列表

有关添加或扩展API的扩展示例，请参阅分类:API扩展 。

测试你的扩展

• 访问api.php并转到为你的模块或查询子模块自动产生的帮助信息。 你的扩展的帮助信息应正确无误。
  • 您在getExamplesMessages()中提供的示例 URL 应出现在「示例」下，请尝试点击它们。
  • 在查询字符串中省略或混淆URL参数，检查扩展的响应。
• 访问Special:ApiSandbox并交互式探索您的API。
• 查看有关你的扩展的其他信息：

api.php?action=paraminfo&modules=myext [在Api沙盒中尝试]