API

Attention visitors

This page discusses the future API for MediaWiki software.

MediaWiki at present has three interfaces:

• Query API for retrieving any information in xml/json/php formats.
• Special:Export feature (bulk export of xml formatted data)
• Regular Web-based interface

Wikimania 2006 API discussion

The whiteboard these notes were taken from

A simple-as-possible API was quickly designed at the Wikimania Hacking Days on 4 August 2006. This minimal API only supports the most essential functions, with the goal of allowing a quick implementation, with other functionality (moving pages, uploading images, etc.) to be specified once a basic API has been implemented.

Login

This function logs the user into mediawiki using a username and password. Other authentication methods could possibly be added in the future.

in

username, password, (API key)

API key is not needed but should be introduced now, as it would make it very difficult to get it in later. --Yurik 14:52, 6 August 2006 (UTC)

out

success, authentication failure, or temporary failure

We can use standard HTTP error codes (500-something is a security error, 200ish - accept, need to lookup the exact codes). --Yurik 14:52, 6 August 2006 (UTC)

Retrieving Data

Please note that a much more extensive interface - Query API is already available for all media wiki servers. It allows developers to minimize the server load and bandwidth consumption by returning only the data specifically requested. By total coincidence the usage is similar to what Yahoo just released at python dev center.

read revision

This function requests the full text of a single article revision, either by article title/page ID, in which case the most recent revision is fetched, or by revision ID. The return value is xml which includes the name of the page, the name of the most recent editor, a revision ID and timestamp, the full wikitext of the revision, and a flag if the article is a redirect, including the name of the page to which it redirects.

in

article title or page ID, or revision ID

out

A format mostly identical to the current special:export, but also including some metadata about whether the page is a redirect, and the page to redirect to, so that the client does not need to parse the wikitext

requesting the redirect information as well as the other information incurs a 30 milisecond performance penalty

in article title, with redirect info

http://meta.wikimedia.org/w/query.php?titles=Main_Page&rvlimit=1&what=namespaces%7Cinfo%7Credirects%7Crevisions%7Ccontent&rvcomments]

in article ID, with redirect info

http://meta.wikimedia.org/w/query.php?pageids=12631&rvlimit=1&what=namespaces%7Cinfo%7Credirects%7Crevisions%7Ccontent&rvcomments

in revision ID, with redirect info

http://meta.wikimedia.org/w/query.php?revids=406406&rvlimit=1&what=namespaces%7Cinfo%7Credirects%7Crevisions%7Ccontent&rvcomments

in article title

http://meta.wikimedia.org/w/query.php?titles=Main_Page&rvlimit=1&what=namespaces%7Cinfo%7Crevisions%7Ccontent&rvcomments

in article ID

http://meta.wikimedia.org/w/query.php?pageids=12631&rvlimit=1&what=namespaces%7Cinfo%7Crevisions%7Ccontent&rvcomments

in revision ID

http://meta.wikimedia.org/w/query.php?revids=406406&rvlimit=1&what=namespaces%7Cinfo%7Crevisions%7Ccontent&rvcomments

read history

This function requests the edit history of an article, referenced either by title, or by page ID. The range start parameter determines the first edit returned, referenced by revision ID or ISO date. The limit parameter determines how many pages before or since that edit should be in the list, up to 5000 revisions, or some other maximum to be determined.

in

article title or page ID, range start, +- limit

range start can be ISO date or revision ID.

if negative range start, fetch last limit revisions bounded by some maximum of revisions: currently 5000

always return up to 5000 revisions

out

export xml metadata (see readrevision)

Submitting Data

This function attempts to save an article to the mediawiki server. The revision ID of the revision the edit is based on is provided so that in the case of an edit conflict, the function will fail. If another edit has been made to the page since the page was loaded, but a simple merge is possible, then the function will succeed.

in

last revision ID or 0 (if the page is new), page text, page title, edit comment, minor edit flag, edit token

out

success(version ID), edit conflict fail, permission failure, temp failure

Notes

Date format:

UTC only, ISO 8601

Date = 0 means the current revision

Simple merges on write:

Because simple merges will be undertaken automatically by mediawiki, it is impossible to assume that when the write article function succeeds, the submitted text is authoritative. If further edits will be made, a new copy of the most recent revision should be fetched from the server.

preexisting

http://en.wikipedia.org/w/query.php