API:Форматы данных

Ввод

API принимает входные данные через параметры, предоставляемые HTTP-запросом в формате application/x-www-form-urlencoded или multipart/form-data. (unlike REST API, the Action API currently does not support application/json input format.) Каждый модуль и подмодуль обладает собственным набором параметров, которые перечислены в документации и в action=help. Их также можно получить через action=paraminfo .

Кодировка

Все вводимые данные должны быть переданы в корректном коде UTF-8, в форме NFC. MediaWiki попытается преобразовать другие форматы. В ходе преобразования может возникнуть ошибка.

Параметры с списком значений

Параметры, которые принимают несколько значений, обычно передаются со значениями, разделенными символом вертикальной черты (|), например param=value1|value2. Если значение содержит в себе символ вертикальной черты, используйте U+001F (Unit Separator) в качестве разделителя и начните перечисление с U+001F, например param=%1Fvalue1%1Fvalue2.

Если параметр принимает несколько значений, это явно указано в документации к модулю.

Булевы параметры

Если в HTTP-запросе указан булевый параметр, он считается истинным независимо от его значения. Для ложного значения опустите параметр полностью. Лучший способ указать истинный параметр в HTTP-запросе — это использование someParam=; завершающий знак = не допускает отбрасывания «пустого» параметра браузером или HTTP-библиотекой.

Временные отметки

Параметры, принимающие временные отметки, способны принять несколько форматов временных отметок:

• формат ISO 8601: 2008-08-23T18:05:46Z.
• Внутренний формат временных отметок MediaWiki : 20080823180546.
• Внутренний формат временных отметок MySQL: 2008-08-23 18:05:46.
• Формат временных отметок Unix 1219514746 (время, прошедшее с 1 января 1970 года, в секундах).

Временные отметки в выходных данных всегда находятся в формате ISO 8601.

Выход

Стандартный формат и формат вывода по умолчанию в MediaWiki — JSON. Все остальные форматы не рекомендуется.

Выходной формат всегда должен указываться с помощью format=yourformat, где yourformat являются одним из следующих:

• json: Формат JSON. (рекомендуемый)
• php: Формат сериализованного PHP. (устарело)
• xml: Формат XML (устарело)
• txt: Формат PHP print_r(). (удалено в 1.27)
• dbg: Формат PHP var_export(). (удалено в 1.27)
• yaml: Формат YAML. (удалено в 1.27)
• wddx: Формат WDDX. (удалено в 1.26)
• dump: Формат PHP var_dump(). (удалено в 1.26)
• none: Возвращает пустой ответ. 1.21+

Пример

Получить выходные данные в JSON.

api.php?action=query&titles=Main%20page&format=json [попробуйте в ApiSandbox]

Ответ

{
  "query": {
    "pages": {
      "217225": {
        "pageid": 217225,
        "ns": 0,
        "title": "Main page"
      }
    }
  }
}

Если не указано иное, все модули поддерживают вывод данных во всех обобщённых форматах. Для облегчения отладки, все обобщённые форматы имеют альтернативы с окончанием fm, в виде форматированного HTML, например jsonfm.

Параметры JSON

Следующие параметры могут использоваться с format=json и format=jsonfm:

• utf8: Кодирует большинство (но не все) не-ASCII символов в UTF-8 вместо замены их на шестнадцатеричные escape-последовательности. Тип: boolean.
• ascii: Кодирует все символы, отличные от ASCII, с помощью шестнадцатеричных escape-последовательностей. Тип: boolean.
• formatversion: Формат вывода. 1.25+
  • 1: Обратно совместимый формат, использует ключи * для узлов содержимого, кодирует символы, отличные от ASCII, используя шестнадцатеричные escape-последовательности.
  • 2: Современный формат. Возвращает ответы в более чистом формате, кодирует большинство символов, отличных от ASCII, как UTF-8. (рекомендуемый)
• callback: Response in the JSON format, by wrapping the result in a JavaScript function call. For security reasons, these responses ignore any browser session cookies and respond without information specific to a current logged-in user. This means the following features are disabled for safety:
  • Токены не могут быть получены, поэтому выполнение изменяющих состояние действий невозможно.
  • Клиент рассматривается как анонимный (не зашедший в свою учётную запись) пользователь, даже если произведён вход посредством action=login . Это означает, что модули, которым требуются дополнительные права, не будут работать, если анонимным пользователям не разрешено их использовать.

Дополнительная информация

• Выходные форматы XML и PHP устарели, но все еще используются. Клиентам, написанным на PHP, следует избегать использования формата PHP, поскольку он фундаментально небезопасен. Он поддерживается на данный момент только ввиду его популярности.
• Существует большое количество библиотек и онлайн-ресурсов для преобразования ответов в формате JSON в другие форматы, например, JSON-CSV преобразовывает JSON в CSV.
• Модули лент, наподобие ленты свежих правок, переопределяют стандартный формат вывода, вместо этого используя RSS или Atom, как указано в их параметре feedformat. В этих случаях формат, указанный в параметре format используется только при возникновении ошибки.

См. также

• API:Errors and warnings - Содержит форматы предупреждений и ошибок.

• Maintained by MediaWiki Interfaces Team.
• Live chat (IRC): #mediawiki-core ^{подключиться}
• Issue tracker: Phabricator MediaWiki-Action-API (Report an issue)