API:Data formats

From MediaWiki.org

This page is part of the MediaWiki API documentation.

Language:

English  • Deutsch  • Español  • Français  • 日本語  • Русский  • Українська

[edit] Input

The API takes its input through parameters in the query string. Every module (and every action=query submodule) has its own set of parameters, which is listed in the documentation and in action=help, and can be retrieved through action=paraminfo.

[edit] Multivalue parameters

Some parameters take multiple values, separated by a pipe character (|). Whether a parameter accepts multiple values is listed explicitly in action=paraminfo and action=help. The documentation does not distinguish multivalue parameters explicitly, but the descriptions for these parameters are usually along the lines of "A list of ..." or "A pipe-separated list of ...".

[edit] Timestamps

Parameters that take timestamp values accept multiple timestamp formats:

• ISO 8601 format: 2008-08-23T18:05:46Z
• MediaWiki's internal timestamp format: 20080823180546
• MySQL's internal timestamp format 2008-08-23 18:05:46
• UNIX timestamp format (number of seconds since January 1, 1970)

In the output, timestamps are always in ISO 8601 format.

[edit] Output

MediaWiki API supports a number of generic output formats (XML,JSON,YAML,...), and some domain specific formats (RSS, ...) for special modules.

Unless specified, all modules allow data output in all generic formats. To simplify debugging, all generic formats have "pretty-print in HTML" alternatives with 'fm' suffix. By default, xmlfm format is used.

Note that while the pretty-print formats are all indented and separate syntactic elements with newlines, the non-pretty formats don't do this (except for YAML, because indentation is part of its syntax).

[edit] JSON callback restrictions

When using JSON in callback mode, a number of things are disabled for security:

• Tokens cannot be obtained (so state-changing actions aren't possible)
• The client is treated as an anonymous user (i.e. not logged in) for all purposes, even after logging in through action=login
  • This means that things that require additional rights, such as rcprop=patrolled, won't work unless anonymous users are allowed to use them

[edit] Examples

XML

<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <pages>
      <page pageid="736" ns="0" title="Albert Einstein" touched="2007-07-06T04:37:30Z" lastrevid="142335140" counter="4698" length="86906" />
    </pages>
  </query>
</api>

JSON

{
    "query": {
        "pages": {
            "736": {
                "pageid": 736,
                "ns": 0,
                "title": "Albert Einstein",
                "touched": "2007-07-06T04:37:30Z",
                "lastrevid": 142335140,
                "counter": 4698,
                "length": 86906
            }
        }
    }
}

YAML

---
query: 
  pages: 
    - 
      pageid: 736
      ns: 0
      title: Albert Einstein
      touched: |
        2008-03-16T04:59:39Z
      lastrevid: 198568286
      counter: 4698
      length: 81076

WDDX

<?xml version="1.0" encoding="utf-8"?>
<wddxPacket version="1.0">
  <header/>
  <data>
    <struct>
      <var name="query">
        <struct>
          <var name="pages">
            <struct>
              <var name="736">
                <struct>
                  <var name="pageid">
                    <number>736</number>
                  </var>
                  <var name="ns">
                    <number>0</number>
                  </var>
                  <var name="title">
                    <string>Albert Einstein</string>
                  </var>
                  <var name="touched">
                    <string>2007-07-06T04:37:30Z</string>
                  </var>
                  <var name="lastrevid">
                    <number>142335140</number>
                  </var>
                  <var name="counter">
                    <number>4698</number>
                  </var>
                  <var name="length">
                    <number>86906</number>
                  </var>
                </struct>
              </var>
            </struct>
          </var>
        </struct>
      </var>
    </struct>
  </data>
</wddxPacket>

PHP (serialized format, with line breaks added for readability. Use PHP's unserialize() function to recover data.)

a:1:{s:5:"query";a:1:{s:5:"pages";a:1:{i:736;a:7:{s:6:"pageid";i:736;s:2:"ns";i:0;s:5:"title";s:15:"Albert Einstein";
s:7:"touched";s:20:"2007-07-06T04:37:30Z";s:9:"lastrevid";i:142335140;s:7:"counter";i:4698;s:6:"length";i:86906;}}}}

PHP (var_export format. Use PHP's eval() function to recover data.)

array (
  'query' => 
  array (
    'pages' => 
    array (
      736 => 
      array (
        'pageid' => 736,
        'ns' => 0,
        'title' => 'Albert Einstein',
        'touched' => '2008-10-11T20:27:04Z',
        'lastrevid' => 244636163,
        'counter' => 4698,
        'length' => 89641,
      ),
    ),
  ),
)