API:扩展

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Extensions and the translation is 21% complete.

Other languages:
Deutsch • ‎English • ‎dansk • ‎português • ‎русский • ‎العربية • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
Gnome-preferences-other.svg 扩展: 开发 标签扩展 手册:解析器函数 钩子 特殊页面 手册:皮肤 手册:魔術字 API Content models

This document covers creating an API module in an extension for use with MediaWiki 1.30 and later.

模块创建与注册

All API modules are subclasses of ApiBase , but some types of modules use a derived base class. The method of registration also depends on the module type.

action modules
Modules that provide a value for the main action parameter should subclass ApiBase . They should be registered in extension.json using the APIModules key.
format modules
Modules that provide a value for the main format parameter should subclass ApiFormatBase. They should be registered in extension.json using the APIFormatModules key. It's very uncommon for an extension to need to add a format module.
query submodules
Modules that provide a value for the prop, list, or meta parameters to action=query should subclass ApiQueryBase (if not usable as a generator) or ApiQueryGeneratorBase (if usable as a generator). They should be registered in extension.json using the APIPropModules, APIListModules, or APIMetaModules key.

In all cases, the value for the registration key is an object with the module name (i.e. the value for the parameter) as the key and the class name as the value. Modules may also be registered conditionally using the ApiMain::moduleManager (for action and format modules) and ApiQuery::moduleManager (for query submodules) hooks.

Implementation

前缀

In the constructor of your API module, when you call parent::__construct() you can specify an optional prefix for your module's parameters. (In the generated documentation for a module this prefix, if any, appears in parentheses in the heading for the module.) 如果你的模块是一个可以查询的子模块,那么需要一个前缀,因为客户可以在同一个请求中使用多个子模块,其中每个都有自己的参数。对于动作和格式模块,没有必要使用前缀。

参数

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->extractRequestParameters() 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 an 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.

Master database access

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

返回错误

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

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 maintain extra API documentation on WikiMedia.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 开始,可以使用下列钩子拓展和讯模块的功能:

List of extensions with API functionality

See API extensions for examples of extensions that add to or extend the API.

测试你的扩展

  • 访问 api.php 并转到为你的模块或查询子模块自动产生的帮助信息。 Your extension's help information should be correct.
    • The example URLs you provided in getExamplesMessages() should appear under "Examples", try clicking them.
    • Omit and mangle URL parameters in the query string, check your extension's response.
  • Visit Special:ApiSandbox and interactively explore your API.
  • Visit to see additional information about your extension.