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 не викине someParam як порожній.

Часові позначки

Параметри, які набувають значень часової позначки, приймають часову позначку в різних форматах:

• формат ISO 8601: 2008-08-23T18:05:46Z.
• внутрішній формат часової позначки MediaWiki : 20080823180546.
• внутрішній формат часової позначки MySQL: 2008-08-23 18:05:46.
• формат часової позначки UNIX 1219514746 (кількість секунд від 1 січня 1970 року).

Виводяться часові позначки завжди у форматі ISO 8601.

Вихід

• Авторизуватися у вікі, отримати дані та відобразити результат — все за допомогою запитів HTTP до веб-служби

Формат виходу завжди має бути заданий за допомогою format=yourformat із yourformat і є одним із:

• json: формат JSON (рекомендовано)
• php: серіалізований PHP-формат. (deprecated)
• xml: формат XML. (deprecated)
• txt: формат PHP print_r() (removed in 1.27)
• dbg: формат PHP var_export() (removed in 1.27)
• yaml: формат YAML (removed in 1.27)
• wddx: формат WDDX (removed in 1.26)
• dump: формат PHP var_dump() (removed in 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"
      }
    }
  }
}

Якщо не вказано інше, кожен модуль дозволяє виводити дані у всіх загальних форматах. Для спрощення налагодження всі загальні формати мають альтернативи типу «pretty-print in HTML», записані із суфіксом fm, як-от jsonfm.

Параметри JSON

Наступні параметри можуть бути застосовані з format=json та format=jsonfm:

• utf8: Закодовує більшість (але не всі) символи не-ASCII у UTF-8, замість заміни їх шістнадцятковими керівними послідовностями. Тип: boolean.
• ascii: Закодовує всі символи не-ASCII як шістнадцяткові керівні послідовності. Тип: boolean.
• formatversion: Форматування виводу. 1.25+
  • 1: Сумісний із попередніми формат застосовує ключ * для вузлів вмісту та кодує не-ASCII символи як шістнадцяткові керівні послідовності.
  • 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 перетворює на перелік розділених комою значень.
• Модулі завантаження на кшталт Завантаження нових змін застосовують відмінний від стандартного формат виводу, як-от RSS чи Atom, як указано в їхньому параметрі feedformat. В таких випадках формат, указаний параметром format, застосовується лише при виникненні помилки.

Див. також

• API:Errors and warnings - Містить формати попереджень і помилок.

• Maintained by MediaWiki Interfaces Team.
• Live chat (IRC): #mediawiki-core ^connect
• Issue tracker: Phabricator MediaWiki-Action-API (Report an issue)