API:Data formats

From MediaWiki.org
Jump to: navigation, search
Translate this page
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎日本語 • ‎한국어 • ‎polski • ‎русский • ‎українська
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page



MediaWiki action API

v · d · e

Input[edit | edit source]

The API takes its input through parameters provided by the query string or from a POST entity in application/x-www-form-urlencoded or multipart/form-data format. 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.

Multivalue parameters[edit | edit source]

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 ...".

Boolean values[edit | edit source]

Boolean parameters work like HTML checkboxes: if the parameter is specified in the HTTP request, regardless of value, it is considered true. For a false value, omit the parameter entirely. The best way to specify a true parameter in an HTTP request is to use someParam=; the trailing = ensures the browser or HTTP library does not discard the "empty" someParam.

Timestamps[edit | edit source]

Parameters that take timestamp values accept multiple timestamp formats:

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

Output[edit | edit source]

MediaWiki API supports a number of generic output formats (XML, JSON, YAML, ...), and some domain-specific formats (RSS, ...) for special modules. You should always specify the format with the input (request) parameter format and a lowercase value. Starting with version 1.24, all formats other than JSON, XML and PHP are deprecated and are scheduled for removal in 1.26 and 1.27. All new API users should use JSON. Clients written in PHP should avoid using the PHP format because it is fundamentally insecure. It is maintained only due to its popularity.

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.

The default format changed in MediaWiki 1.25 to jsonfm, it was xmlfm in earlier MediaWiki releases.

Note that while the pretty-print formats are all indented and separate syntactic elements with newlines, the non-pretty formats don't do this.

Format Description
json JSON format
php serialized PHP format
xml XML format
Deprecated formats
wddx WDDX format
yaml YAML format
txt PHP print_r() format
dbg PHP var_export() format
dump PHP var_dump() format

There are many conversion libraries and online converters to convert JSON responses to other formats, for example http://json-csv.com converts to Comma-Separated Values

JSON parameters[edit | edit source]

format=json and jsonfm accept the following additional parameters:

  • callback: If specified, wraps the output into a given function call. For safety, all user-specific data will be restricted.
  • utf8: If specified, encodes most (but not all) non-ASCII characters as UTF-8 instead of replacing them with hexadecimal escape sequences.
  • formatversion Specify formatversion=2 for to get json (and php) format responses in a cleaner format. MW 1.25+

Callback restrictions[edit | edit source]

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

Examples[edit | edit source]

JSON/YAML

api.php?action=query&titles=Albert%20Einstein&prop=info&format=jsonfm [try in ApiSandbox]
Result 
{
    "query": {
        "pages": {
            "736": {
                "pageid": 736,
                "ns": 0,
                "title": "Albert Einstein",
                "touched": "2007-07-06T04:37:30Z",
                "lastrevid": 142335140,
                "counter": 4698,
                "length": 86906
            }
        }
    }
}

it may be useful to add the '&indexpageids' parameter, to parse the json if the pageid ("736") is not known before the result.

JSON utf8 content on a French page, remove the utf8= parameter to see the difference

api.php?action=query&titles=Façade&prop=revisions&rvprop=content&format=jsonfm&utf8= [try in ApiSandbox]

XML

api.php?action=query&titles=Albert%20Einstein&prop=info&format=xmlfm [try in ApiSandbox]
Result 
<?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>

WDDX

api.php?action=query&titles=Albert%20Einstein&prop=info&format=wddxfm [try in ApiSandbox]
Result 
<?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.)

api.php?action=query&titles=Albert%20Einstein&prop=info&format=php [try in ApiSandbox]
Result 
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.)

api.php?action=query&titles=Albert%20Einstein&prop=info&format=dbg [try in ApiSandbox]
Result 
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,
      ),
    ),
  ),
)
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Data_formats&oldid=1868413"