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
Login
Request:
api.php ? action=login & name=Yurik & password=12345 [& domain=wikipedia.org]
Result:
api:
login:
result: Success Other values: NoName, Illegal, WrongPluginPass,
NotExists, WrongPass, EmptyPass
token: 1234567890ABCDEF Also returned as a cookie (i.e. enwikiToken)
userName: Yurik Also returned as a cookie (i.e. enwikiUserName)
userID: 12345 Also returned as a cookie (i.e. enwikiUserID)
Query Data
General
Limits
- To prevent server overloads, each query imposes a limit on how many items it can process. Anonymous and logged-in users have one limit, while bots have a considerably higher limit as they are trusted by the community. At present, each query simply lists the maximum request size it allows. For example, allpages list will allow aplimit= to be set no higher than 500, or in case of a bot - no higher than 5000.
- Drawbacks: Currently all limits are additive, so if the user requests allpages and backlinks, the user will get 500 of each. This is not very good, as the more items are compounded into one request, the heavier the load on the server will be. Instead, some sort of a weighted mechanism should be developed, where each request item has a certain "cost" associated with it, and each user is allocated a fixed allowance per request. The more information user requests, the less the limit becomes for that request. Unfortunately, that makes it very hard to figure out the maximum limits before executing the query, so might not be a workable solution.
Title Normalization
- Converts improper page titles to their proper form. Capitalizes first character, replaces '_' with ' ', changes canonical namespace names to their localized alternatives, etc.
Request: Note: articleA's first letter is not capitalized
api.php ? action=query & titles=Project:articleA|ArticleB
Result:
api:
query:
pages:
Wikipedia:ArticleA: Project: is converted to Wikipedia: when running on en-wiki.
ns: 4 Show title's namespace except when ns=0
ArticleB:
normalized: Any requested titles not in the "proper" form will be here
Project:articleA: Wikipedia:ArticleA
Redirects
- Redirects can be resolved by the server, so that the target of redirect is returned instead of the given title. This example is not very usefull without additional prop=... element, but shows the usage of redirect function. The 'redirects' section will contain the target of redirect and non-zero namespace code. Both normalization and redirection may take place. In case of redirect to a redirect, all redirections will be solved, and in case of a circular redirection, there might not be a page in the 'pages' section.
Request:
api.php ? action=query & titles=Main page & redirects
Result:
api:
query:
pages:
Main Page:
redirects:
Main page: Main Page
Circular Redirects
- Assume Page1 → Page2 → Page3 → Page1 (circular redirect). Also, in this example a non-normalized name 'page1' is used.
Request:
api.php ? action=query & titles=page1 & redirects
Result:
api:
query:
redirects:
Page1: Page2 Redirects are present, but not the 'pages' element.
Page2: Page3
Page3: Page1
normalized:
page1: Page1
Page Information
Page information items are used to get various data about a list of pages provided with the titles= parameter. Content, links, interwiki links, and other information may be obtained.
categories (cl)
- Gets a list of all templates used on the provided pages. Limit: 200/1000.
- Parameters: extrainfo (adds sortkey & timestamp).
content (??)
- Returns wiki markup for the given list of articles. Requesting content is just a shorthand for the last revision request with content, so it would be equivalent to prop=revisions & rvprop=content without any other rv* parameters. Limit: No more than 50 (user) / 200 (bot) page contents per request.
Request:
api.php ? action=query & prop=content & titles=ArticleA|ArticleB
Result:
api:
query:
pages:
ArticleA:
id: 12345
lastrev: 67890
revisions:
67890:
content: ...raw page content...
ArticleB:
id: 0 ID=0 when title does not exist
langlinks (ll)
- Gets a list of all language links (interwikies) from the provided pages to other languages. Limit: 200/1000.
links (pl)
- Gets a list of all links from the provided pages. Limit: 200/1000.
- Parameters: namespace (flt).
templates (tl)
- Gets a list of all templates used on the provided pages. Limit: 200/1000.
Revisions
- Returns revisions for a given article based on the selection criteria. Revisions may be used with multiple titles only when working with the latest revision. When using rvlimit, rvdir=newer, rvstart, or rvend parameters, titles= must have only one title listed. By default, revisions shows only the id of the last revision.
Request:
api.php ? action=query & prop=revisions & titles=ArticleA & rvprop=timestamp|user|comment|content
Result:
api:
query:
pages:
ArticleA:
id: 12345
lastrev: 67890
revisions:
67890:
timestamp: 20060908025739
user: UserX
comment: ...change comment...
content: ...raw revision content...
- Additional 'revisions' samples
- Get the timestamps of up to 10 revisions, begining at 2006-09-01 and moving forward in time.
api.php ? action=query & prop=revisions & titles=ArticleA & rvprop=timestamp & rvlimit=10 & rvdir=newer & rvstart=20060901000000
- Get the timestamps of all revisions for the entire month of September 2006. rvlimit is optional. If the number of revisions exceeds the limit, the 'revisions' element will contain 'continue':'rvstart=20060920122343' with the timestamp to continue from.
api.php ? action=query & prop=revisions & titles=ArticleA & rvprop=timestamp & rvstart=20060901000000 & rvend=20061001000000
- Get the timestamps of up to 10 revisions, begining at 12345 and moving back in time. If more than 10 revisions are available, 'revisions' element will contain 'continue':'revids=23512' , where revid is the next revision id in order.
api.php ? action=query & prop=revisions & revids=12345 & rvprop=timestamp & rvlimit=10 & rvdir=older
- Get the timestamps of all revisions between two given revision IDs. rvlimit is optional. If the number of revisions exceeds the limit, the 'revisions' element will contain 'continue':'rvstartid=23512' with the revid to continue from. Both rvstartid & rvendid must belong to the same title. The titles= parameter is not required, but if given, it must be set to the same title as revision IDs.
api.php ? action=query & prop=revisions & rvprop=timestamp & rvstartid=12345 & rvendid=67890
Lists
Lists differ from other properties in two aspects - instead of appending data to the elements under 'pages' element, each list has its own separated branch under 'query' element. Also, list output is limited by number of items, and may be continued using "paging" technique. Even when no limit is provided, the query will only return a set number of items, and will also provide a string point from which to continue paging. See allpages list for an example.
allpages (ap)
- Returns a list of pages in a given namespace starting at from, ordered by page title.
- Parameters: from (paging), namespace (dflt=0), redirect (flt), limit (dflt=10, max=500/5000)
- Example: Request a list of 3 pages from namespace 10 (templates) begining at the first available page.
Request:
api.php ? action=query & list=allpages & apnamespace=10 & aplimit=3
Result:
api:
query:
allpages:
Template:A-Article:
id: 12341
ns: 10
Template:B-Article:
id: 12342
ns: 10
Template:C-Article:
id: 12343
ns: 10
query-status:
allpages:
continue: apfrom=D-Article The next item in this list would have been Template:D-Article.
- The client may now make another request using the continue value as a parameter:
api.php ? action=query & list=allpages & apnamespace=10 & aplimit=3 & apfrom=D-Article
backlinks (bl)
- Lists pages that link to the given page. Ordered by linking page title.
- Parameters: title, from (paging), namespace (flt), redirect (flt), limit (dflt=10, max=500/5000)
api.php ? action=query & list=backlinks & bltitle=ArticleA
categorymembers (cm)
- List of pages that belong to a given category, ordered by page title.
- Parameters: title (if title is in NS 0, treats it as category NS), from (paging), namespace (flt), limit (dflt=10, max=500/5000)
api.php ? action=query & list=categorymembers & cmtitle=category:title
embeddedin (ei)
- What pages include template:title page as a template. List of pages that include the given page using {{title}}. Ordered by including page title.
- Parameters: category title, from (paging), namespace (flt), redirect (flt), limit (dflt=10, max=500/5000)
api.php ? action=query & list=embeddedin & eititle=template:title
imagelinks (il)
- List of pages that include a given image. Ordered by page title.
- Parameters: image title (if image title is in NS 0, treats it as image NS), from (paging), namespace (flt), limit (dflt=10, max=500/5000)
api.php ? action=query & list=imagelinks & iltitle=image:title
logevents (le)
- List log events, filtered by time range, event type, user type, or the page it applies to. Ordered by event timestamp.
- Parameters: type (flt), from (paging timestamp), to (flt), direction (dflt=older), limit (dflt=10, max=500/5000), user (flt), title (flt)
api.php ? action=query & list=logevents - List last 10 events of any type
recentchanges (rc)
- Gets a list of pages recently changed, ordered by modification timestamp.
- Parameters: from (paging timestamp), to (flt), namespace (flt), minor (flt), usertype (dflt=!bot), direction (dflt=older), limit (dflt=10, max=500/5000)
api.php ? action=query & list=recentchanges - List last 10 changes
usercontribs (uc)
- Gets a list of pages modified by a given user, ordered by modification time.
- Parameters: user, from (paging timestamp), to (flt), namespace (flt), minor (flt), top (flt), direction (dflt=older), limit (dflt=10, max=500/5000)
api.php ? action=query & list=usercontribs & ucuser=User:UserA - List last 10 changes made by userA
users (us)
- Gets a list of registered users, ordered by user name.
- Parameters: from (paging), limit (dflt=10, max=500/5000)
watchlist (wl)
- Get a list of pages on the user's watchlist but only if they were changed within the given time period. Ordered by time of the last change of the watched page.
- Parameters: from (paging timestamp), to (flt), namespace (flt), direction (dflt=older), limit (dflt=10, max=500/5000)
Generators
Generator is way to use one of the above #lists instead of the titles= parameter. The output of the list must be a list of pages, whose titles get automatically used instead of the titles=/revids=/pageids= parameters. Other queries such as content, revisions, etc, will treat those pages as if they were provided by the user in the titles= parameter. Only one generator is allowed, and while it is possible to have both generator= and list= parameters in the same call, they may not contain the same values.
- Example: Use the allpages list as a generator, to get the links and categories for all titles returned by allpages.
Request:
api.php ? action=query & generator=allpages & apnamespace=3 & aplimit=10 & apfrom=A & prop=links|categories
Result:
api:
query:
pages:
Template:A-Article:
id: 12341
ns: 10
links:
Linked Article1: Linked Article1 is in the main namespace
Talk:Linked Article2: For non-main ns, list it as a subelement
ns: 1
...
categories:
Category:Cat1:
Category:Cat2:
...
Template:B-Article:
...
Template:C-Article:
...
query-status:
allpages:
continue: apfrom=D-Article The next item in this list would have been Template:D-Article.
- Complex example: Using a "links" page property as a generator. This query will get all the links from all the pages that are linked from Title. For this example, assume that Title has links to TitleA and TitleB. TitleB is a redirect to TitleC. TitleA links to TitleA1, TitleA2, TitleA3; and TitleC links to TitleC1 & TitleC2. Redirect is solved because of the "redirects" parameter.
- The query will execute the following steps:
- For all pages specified in titles=...|... parameter, get all links, and substitute original with the new titles=...|... parameter.
- Execute regular prop=links query using the internally created list of titles.
Request:
api.php ? action=query & generator=links & titles=TitleA & prop=links & redirects
Result:
api:
query:
pages:
TitleA:
id: 12341
links:
TitleA1:
TitleA2:
TitleA3:
TitleC:
id: 12342
links:
TitleC1:
TitleC2:
redirects:
TitleB: TitleC
Posting Data
Request:
api.php ? action=save & title=Project:articleA & edittoken=abc123 & summary=...lalala... & content=...wikitext...
Result:
api:
save:
status: Success Other values: 'Prohibited', 'Conflict', 'DbLcoked', 'BadToken''
title: Wikipedia:ArticleA Always returns normalized title
ns: 4 Show title's namespace except when ns=0
revid: 67891 On success, the new latest revision id