Jump to content

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

From mediawiki.org
This page is a translated version of the page API:Data formats and the translation is 95% complete.

Ввод

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.

Выход

Стандартный формат и формат вывода по умолчанию в 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.

Ответ

{
  "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 используется только при возникновении ошибки.

См. также