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.

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

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

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

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

Документация
The API is documented using MediaWiki's i18n mechanism. Needed messages generally have default names based on the modules "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  message, which should be a one-line description of the module. If additional help text is needed,  may be created as well. Each parameter will need a  message, and parameters using   will also need a   for each value.

More details on API documentation are available at.

Extending core modules
Since MediaWiki 1.14, it's possible to extend core modules' functionality using the following hooks:


 * APIGetAllowedParams to add or modify the module's parameter list
 * APIGetParamDescription 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,   and   modules
 * If the module is run in generator mode, APIQueryGeneratorAfterExecute will be called instead

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

Testing your extension

 * Visit [/api.php api.php] and navigate to the generated help for your module or query submodule. Your extension's help information should be correct.
 * The example URLs you provided in  should appear under "Examples", try clicking them.
 * Omit and mangle URL parameters in the query string, check your extension's response.
 * Install and interactively explore your API.
 * Visit to see additional information about your extension.