API:Data formats
This page is part of the MediaWiki action API documentation. |
MediaWiki action API
- Introduction and quick start
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Searching (by title, content, coordinates...)
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Create and edit pages
- Move pages
- Merge pages
- Rollback
- Delete pages
- Restore deleted revisions
- (Un)protect pages
- (Un)block users
- (Un)watch pages
- Mark revisions of watched pages as visited
- Send email
- Patrol changes
- Import pages
- Change user group membership
- Upload files
- User options
- Tokens
- Page language
- More...
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
- Asserting
Contents
Input[edit]
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.
Encoding[edit]
All input should be valid UTF-8, in NFC form. MediaWiki will attempt to convert other formats but in some cases they might result in an error.
Multivalue parameters[edit]
Some parameters take multiple values, separated by a pipe character (|
). For example, to submit the three values red
, green
and blue
for the parameter color
, you'd put color=red|green|blue
in the query. 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 ...".
If you need to submit a list of values where some of the values contain a pipe character (which should be rare - most multivalue parameters are lists of page titles or usernames, neither of which can contain pipes), you can use the unit separator character instead: color=<US>r|ed<US>gr|een<US>bl|ue
(where <US>
stands for U+001F) will submit the three values r|ed
, gr|een
and bl|ue
. (Note that there is an extra <US>
at the beginning. This is mandatory to avoid ambiguity around submitting a single value containing a pipe.)
Boolean values[edit]
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]
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
1219514746
(number of seconds since January 1, 1970)
In the output, timestamps are always in ISO 8601 format.
Output[edit]
MediaWiki API has historically supported a number of different formats, but this has significantly complicated further development. We would like to standardize on just one JSON format. For now, MediaWiki discourages, but still supports two additional generic output formats (XML and PHP). You should always specify the format with the input (request) parameter format
and a lowercase value. Feed modules like Feed Recent Changes override the standard output format, instead using RSS or Atom, as specified by their feedformat
parameter. In those cases, the format specified in the format
parameter is only used if there's an error. All formats other than JSON are deprecated. XML and PHP are still supported, but all others have been removed in either MediaWiki 1.26 or 1.27; see the table below. 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 for now 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 an 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 (always use this one) | |
none | Always return a blank response 1.21+ | |
Deprecated, but still operational | ||
php | serialized PHP format | |
xml | XML format | |
Formats removed in MediaWiki 1.26 | ||
wddx | WDDX format | |
dump | PHP var_dump() format | |
Formats removed in MediaWiki 1.27 | ||
txt | PHP print_r() format | |
dbg | PHP var_export() format | |
yaml | YAML format |
There are many conversion libraries and online converters to convert JSON responses to other formats—for example, JSON-CSV converts to Comma-Separated Values
JSON parameters[edit]
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
Specifyformatversion=2
for to get json (and php) format responses in a cleaner format. This also encodes most non-ASCII characters as UTF-8. MW 1.25+
Callback restrictions[edit]
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
- This means that things that require additional rights, such as
Examples[edit]
JSON
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
XML
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>
|
PHP (serialized format, with line breaks added for readability. Use PHP's unserialize() function to recover data.)
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)
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,
),
),
),
)
|