API:Расширения
Эта страница является частью документации по API действий MediaWiki. |
В этом документе описывается создание модуля API в расширении для MediaWiki 1.30 или более поздних версий.
Создание и регистрация модуля
Все модули API являются подклассами ApiBase , но некоторые типы модулей наследуют от производного класса. Также от типа модуля зависит метод регистрации.
- модули действий (action)
- Модули, предоставляющие значение для основного параметра
action
, должны быть подклассами ApiBase . Их нужно зарегистрировать вextension.json
, используя ключAPIModules
. - модули форматов (format)
- Модули, предоставляющие значение для основного параметра
format
, должны быть подклассами ApiFormatBase. Их нужно зарегистрировать вextension.json
, используя ключAPIFormatModules
. Необходимость модуля формата в расширении встречается очень редко. - подмодули запросов (query)
- Модули, предоставляющие значения для параметров
prop
,list
илиmeta
к действиюaction=query
, должны быть подклассами ApiQueryBase (если модули не могут использоваться в качестве генераторов) или ApiQueryGeneratorBase (если модули могут использоваться в качестве генераторов). Их нужно зарегистрировать вextension.json
используя ключAPIPropModules
,APIListModules
илиAPIMetaModules
.
Во всех случаях значение ключа регистрации — объект, где ключ — название модуля, а значение — название класса. Модули также могут быть зарегистрированы условно, если использовать хуки ApiMain::moduleManager (для модулей действий и форматов) и ApiQuery::moduleManager (для подмодулей запросов).
Реализация
Префикс
Когда вы вызываете parent::__construct()
в конструкторе вашего модуля API, вы можете также указать префикс для параметров вашего модуля.
(В генерируемой документации модуля этот префикс, если он присутствует, будет указан в круглых скобках в заголовке модуля.)
Если ваш модуль — подмодуль запроса (query), префикс обязателен, так как клиент в одном запросе может вызвать несколько подмодулей, каждый со своими параметрами.
В случае с модулями действия или форматирования префикс необязателен.
Параметры
Большинство модулей требуют параметры.
Они определяются путём реализации getAllowedParams().
Значение, возвращаемое этим методом, — ассоциативный массив, в котором ключи — названия параметров (без префикса), а значения — или скалярные значения параметра по умолчанию, или массивы, определяющие свойства параметра, используя определённые в ApiBase константы PARAM_*
.
На этом примере показан синтаксис и некоторые наиболее распространённые константы PARAM_*
.
protected function getAllowedParams() {
return [
// Необязательный параметр со значением по умолчанию
'simple' => 'value',
// Обязательный параметр
'required' => [
ApiBase::PARAM_TYPE => 'string',
ApiBase::PARAM_REQUIRED => true,
],
// Параметр, который может получать несколько значений в виде списка.
'variable' => [
// Используемый по умолчанию список значений
ApiBase::PARAM_DFLT => 'foo|bar|baz',
// Все возможные значения
ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
// Указание, что можно принимать несколько значений
ApiBase::PARAM_ISMULTI => true,
// Использовать стандартные сообщения документации, «по одному на значение»
ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
],
// Стандартный параметр «limit» (предел объёма выдаваемой информации). От этого стандарта обычно не следует отклоняться.
'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,
],
];
}
Параметры документируются с использованием i18n механизма MediaWiki. Подробности в разделе #Documentation.
Выполнение и вывод
Код, реализующий модуль, размещается в методе execute(). Такой код, как правило, использует $this→extractRequestParams() для получения входных параметров, а также $this→getResult() для получения объекта ApiResult, в который будет добавлен вывод.
Подмодули запроса типа prop должны использовать $this→getPageSet() для получения списка обрабатываемых страниц.
Подмодули запроса, которые могут быть использованы в качестве генераторов, также должны реализовать метод executeGenerator(), которому передаётся объект ApiPageSet, пополняемый генерируемыми страницами.
В этом случае ApiResult
обычно не следует использовать.
Кэширование
По умолчанию ответы API указываются как не подлежащие кэшированию ('Cache-Control: private')!
Для модулей действий вы можете разрешить кэширование, вызвав $this→getMain()→setCacheMode().
При этом от клиентов нужно будет передать параметр maxage
или smaxage
, чтобы кэширование было включено.
Принудительно включить кэширование можно, вызвав $this→getMain()→setCacheMaxAge().
В случае с модулями запроса не вызывайте эти методы. Вместо этого кэширование можно разрешить, реализовав getCacheMode().
И в том, и в другом случае важно убедиться, что приватные данные не разглашаются.
Обработка токенов
Если ваш модуль действия как-либо изменяет вики, ему следует требовать какой-либо токен.
Чтобы это обрабатывалось автоматически, реализуйте метод needsToken()
, возвращая из него тип необходимого токена (скорее всего это токен редактирования 'csrf'
).
В этом случае базовый код API автоматически проведёт проверку токена, предоставленого клиентом в параметре token
запроса к API.
Если вы не хотите использовать токен, который является частью ядра, а предпочитаете пользовательский токен с вашими собственными проверками разрешений, используйте хук ApiQueryTokensRegisterTypes для регистрации вашего токена.
Доступ к главной базе данных
Если ваш модуль обращается к главной базе данных, в нём следует реализовать метод isWriteMode()
, чтобы он возвращал true
.
Возврат ошибок
ApiBase включает несколько методов для разного рода проверки вводимых данных, например:
- Если вам нужно удостовериться, что из набора параметров указан ровно один, используйте $this→requireOnlyOneParameter().
- Если вам нужно удостовериться, что из набора параметров указано не более одного, используйте $this→requireMaxOneParameter().
- Если вам нужно удостовериться, что из набора параметров указано не менее одного, используйте $this→requireAtLeastOneParameter().
- Если вам нужно удостовериться, что у участника есть определённые права, используйте $this→checkUserRightsAny().
- Если вам нужно удостовериться, что участник может выполнить действие на заданной странице, используйте $this→checkTitleUserPermissions().
- Если участник заблокирован (и для вашего модуля это важно), передайте объект
Block
методу $this→dieBlocked().
Вам нередко придётся сталкиваться с необходимостью вызвать ошибку самостоятельно.
Обычно это делается путём вызова $this→dieWithError(), но если у вас есть значение StatusValue
с информацией об ошибке, вы можете передать его $this→dieStatus(), а не вызывать указанный выше метод.
Если вам нужно вернуть предупреждение, а не ошибку, используйте $this→addWarning() или $this→addDeprecation(), если вы сообщаете об устаревании использованных клиентом возможностей.
Документация
API документируется посредством встроенного в MediaWiki механизма i18n. Необходимые сообщения обычно имеют имена по умолчанию, основанные на «пути» модуля. В случае с модулями действий и форматов путь такой же, как использованное при регистрации название модуля. В случае с подмодулями запросов путь — название модуля с префиксом "query+".
Каждому модулю потребуется сообщение за apihelp-$path-summary
, которое должно быть однострочным описанием модуля.
Если требуется дополнительный текст справки, также можно создать apihelp-$path-extended-description
.
Для каждого параметра потребуется сообщение apihelp-$path-param-$name
, а для параметров, использующих PARAM_HELP_MSG_PER_VALUE
, также потребуется apihelp-$path-paramvalue-$name-$value
для каждого значения.
Больше информации о документировании API указано на странице API:Локализация .
Расширения могут также документировать свои дополнительные модули API на сайте mediawiki.org.
Она должна быть расположена на основной странице расширения, или если для неё нужно много места, на странице Extension:<ExtensionName>/API
или её подстраницах (например как у CentralAuth , MassMessage и StructuredDiscussions ).
Пространство имён API предназначено только для документации API ядра MediaWiki.
Расширение встроенных в ядро модулей
Начиная с MediaWiki 1.14, функциональные возможности встроенных в ядро модулей могут быть расширены с использованием следующих хуков:
- APIGetAllowedParams - позволяет изменять параметры модуля или добавлять новые
- APIGetParamDescriptionMessages - позволяет добавлять или изменять описания параметров модуля
- APIAfterExecute - позволяет выполнять какое-либо действие после исполнения модуля (но до выдачи результата)
- Используйте APIQueryAfterExecute для модулей
prop=
,list=
иmeta=
- Если модуль запущен в режиме генератора, вместо этого хука будет вызван APIQueryGeneratorAfterExecute
- Используйте APIQueryAfterExecute для модулей
Список расширений с функциями для API
Категория Category:API расширений содержит примеры расширений, дополняющих или расширяющих API.
Тестирование своего расширения
- Перейдите на страницу api.php и найдите автоматически сгенерированную документацию по вашему модулю или подмодулю query. Справочная информация по вашему расширению должна быть сгенерирована правильно.
- Примеры URL, которые вы привели в вызовах
getExamplesMessages()
, должны появиться в списке «Примеры». Попробуйте перейти по этим ссылкам. - Поэкспериментируйте, убирая некоторые параметры URL и/или внося намеренные ошибки в них, и посмотрите, как ваше расширение отреагирует на такой ввод.
- Примеры URL, которые вы привели в вызовах
- Перейдите на Special:ApiSandbox и исследуйте свой API в интерактивном режиме.
- Чтобы просмотреть дополнительную информацию о вашем расширении: