API:Extensions/ru

В этом документе описывается создание модуля API в расширении для MediaWiki 1.30 или более поздних версий.

Создание и регистрация модуля
Все модули API являются подклассами, но некоторые типы модулей наследуют от производного класса. Также от типа модуля зависит метод регистрации.


 * модули действий (action)
 * Модули, предоставляющие значение для основного параметра, должны быть подклассами . Их нужно зарегистрировать в  , используя ключ.


 * модули форматов (format)
 * Модули, предоставляющие значение для основного параметра, должны быть подклассами . Их нужно зарегистрировать в  , используя ключ  . Необходимость модуля формата в расширении встречается очень редко.


 * подмодули запросов (query)
 * Модули, предоставляющие значения для параметров,   или   к действию  , должны быть подклассами  (если модули не могут использоваться в качестве генераторов) или  (если модули могут использоваться в качестве генераторов). Их нужно зарегистрировать в   используя ключ  ,   или.

Во всех случаях значение ключа регистрации — объект, где ключ — название модуля, а значение — название класса. Модули также могут быть зарегистрированы условно, если использовать хуки ApiMain::moduleManager (для модулей действий и форматов) и ApiQuery::moduleManager (для подмодулей запросов).

Префикс
Когда вы вызываете  в конструкторе вашего модуля API, вы можете также указать префикс для параметров вашего модуля. (В генерируемой документации модуля этот префикс, если он присутствует, будет указан в круглых скобках в заголовке модуля.) Если ваш модуль — подмодуль запроса (query), префикс обязателен, так как клиент в одном запросе может вызвать несколько подмодулей, каждый со своими параметрами. В случае с модулями действия или форматирования префикс необязателен.

Параметры
Большинство модулей требуют параметры. Они определяются путём реализации. Значение, возвращаемое этим методом, — ассоциативный массив, в котором ключи — названия параметров (без префикса), а значения — или скалярные значения параметра по умолчанию, или массивы, определяющие свойства параметра, используя определённые в константы.

На этом примере показан синтаксис и некоторые наиболее распространённые константы.

Параметры документируются с использованием i18n механизма MediaWiki. Подробности в разделе #Documentation.

Выполнение и вывод
Код, реализующий модуль, размещается в методе. Такой код, как правило, использует для получения входных параметров, а также  для получения объекта, в который будет добавлен вывод.

Подмодули запроса типа prop должны использовать для получения списка обрабатываемых страниц.

Подмодули запроса, которые могут быть использованы в качестве генераторов, также должны реализовать метод, которому передаётся объект , пополняемый генерируемыми страницами. В этом случае  обычно не следует использовать.

Кэширование
По умолчанию ответы API указываются как не подлежащие кэшированию ('Cache-Control: private')! В случае с модулями действий кэширование можно разрешить, вызвав. При этом от клиентов нужно будет передать параметр  или , чтобы кэширование было включено. Принудительно включить кэширование можно, вызвав.

В случае с модулями запроса не вызывайте эти методы. Вместо этого кэширование можно разрешить, реализовав.

И в том, и в другом случае важно убедиться, что приватные данные не разглашаются.

Обработка токенов
Если ваш модуль действия как-либо изменяет вики, ему следует требовать какой-либо токен. Чтобы это обрабатывалось автоматически, реализуйте метод, возвращая из него тип необходимого токена (скорее всего это токен редактирования  ). В этом случае базовый код API автоматически проведёт проверку токена, предоставленого клиентом в параметре  запроса к API.

Доступ к главной базе данных
Если ваш модуль обращается к главной базе данных, в нём следует реализовать метод, чтобы он возвращал.

Возврат ошибок
включает несколько методов для разного рода проверки вводимых данных, например:
 * Если вам нужно удостовериться, что из набора параметров указан ровно один, используйте.
 * Если вам нужно удостовериться, что из набора параметров указано не более одного, используйте.
 * Если вам нужно удостовериться, что из набора параметров указано не менее одного, используйте.
 * Если вам нужно удостовериться, что у участника есть определённые права, используйте.
 * Если вам нужно удостовериться, что участник может выполнить действие на заданной странице, используйте.
 * Если участник заблокирован (и для вашего модуля это важно), передайте объект   методу.

Вам нередко придётся сталкиваться с необходимостью вызвать ошибку самостоятельно. Обычно это делается путём вызова, но если у вас есть значение  с информацией об ошибке, вы можете передать его , а не вызывать указанный выше метод.

Если вам нужно вернуть предупреждение, а не ошибку, используйте или, если вы сообщаете об устаревании использованных клиентом возможностей.

Документация
API документируется посредством встроенного в MediaWiki механизма i18n. Необходимые сообщения обычно имеют имена по умолчанию, основанные на «пути» модуля. В случае с модулями действий и форматов путь такой же, как использованное при регистрации название модуля. В случае с подмодулями запросов путь — название модуля с префиксом «query+».

Каждому модулю потребуется сообщение, в котором следует указать однострочное описание модуля. Также может быть создано сообщение с расширенным описанием,. Каждому параметру потребуется сообщение, а параметры, использующие  , должны обладать сообщением   для каждого значения параметра.

Больше информации о документировании API указано на странице.

Расширение встроенных в ядро модулей
Начиная с MediaWiki 1.14, функциональные возможности встроенных в ядро модулей могут быть расширены с использованием следующих хуков:


 * APIGetAllowedParams позволяет изменять параметры модуля или добавлять новые
 * APIGetParamDescription позволяет добавлять или изменять описания параметров модуля
 * APIAfterExecute позволяет выполнять какое-либо действие после исполнения модуля (но до выдачи результата)
 * Используйте APIQueryAfterExecute для модулей,   и
 * Если модуль запущен в режиме генератора, вместо этого хука будет вызван APIQueryGeneratorAfterExecute

Список расширений с функциями для API
Категория API extensions содержит примеры расширений, дополняющих или расширяющих API.

Тестирование своего расширения

 * Перейдите на страницу [/api.php api.php] и найдите автоматически сгенерированную документацию по вашему модулю или подмодулю query. Справочная информация по вашему расширению должна быть сгенерирована правильно.
 * Примеры URL, которые вы привели в вызовах, должны появиться в списке «Примеры». Попробуйте перейти по этим ссылкам.
 * Поэкспериментируйте, убирая некоторые параметры URL и/или внося намеренные ошибки в них, и посмотрите, как ваше расширение отреагирует на такой ввод.
 * Установите и исследуйте свой API в интерактивном режиме.
 * Перейдите по ссылке, чтобы получить дополнительную информацию о своём расширении.