API:FAQ

Overview
This page provides answers to some frequently asked questions about the MediaWiki Action API.

Also read the . It answers some questions not answered here and points to other useful pages.

What is an API?
An API is an acronym for Application Programming Interface. It allows different applications to communicate with each other. In general terms, it refers to web-based APIs, which use HTTP requests-response mechanism and produce JSON/XML structured data.

What is a REST API?
REST is an acronym for REpresentational State Transfer. A set of guiding principles or constraints define a RESTful system. A RESTful API &mdash; or just a REST API &mdash; adheres to these principles and hence is a faster, more reliable and scalable service.

What can an API do?
See some uses of API.

Where can I learn more about APIs?
Here are a few resources:


 * Understanding APIs
 * An Introduction to API’s
 * What is REST — A Simple Explanation for Beginners, Part 1: Introduction

What is the MediaWiki Action API?
The 1>Special:MyLanguage/API:Main page|MediaWiki Action API is a RESTful  web service that allows users to perform certain wiki-actions like page creation, authentication, parsing, searching, etc.

What can the MediaWiki Action API be used for?
The 1>Special:MyLanguage/API:Main page|MediaWiki Action API can be used to:

obtain meta-information about wikis and public users.
 * access wiki features.
 * interact with a wiki.

The right sidebar points to many features supported by the API. Also, see some 1>Special:MyLanguage/API:Tutorial#Examples_of_projects_using_Action_API|Wikimedia projects that use the MediaWiki Action API.

How can I use (or call) the MediaWiki Action API?
HTTP requests are usually used to call the Action API. For detailed instructions, read the 1>Special:MyLanguage/API:Tutorial#How_to_use_it| tutorial.

To play with the Action API:

Enable your browser's developer console and watch net requests to   as you interact with the wiki.
 * Use the Special:ApiSandbox.

What is a module, a submodule, and a parameter?
The MediaWiki Action API has numerous modules that we use to perform different tasks. In technical terms, a module is a subclass of 1>Special:MyLanguage/Manual:ApiBase.php|ApiBase. A module requires parameters. These parameters may (or may not) be submodules.

Consider the following request: here:

  is the output format.
 *   is a parameter of the 2>API:Main module|main module.
 * <tvar|1> </> is another module. It is called the 2>Special:MyLanguage/API:Query</>| query module.
 * <tvar|1> </> is a parameter of the 2>Special:MyLanguage/API:Query</>| query module.
 * <tvar|1> </> is also a module. It can be called a submodule of <tvar|2> </>.
 * <tvar|1> </> is a parameter of the 2>Special:MyLanguage/API:Search</>| search module. It holds the search string 'abc'.
 * <tvar|1> </> is a parameter of the 2>API:Main module</>|main module.

Also, see 1>Special:MyLanguage/API:Query#Introduction and guidelines</>|Introduction and guidelines. It describes the submodules of the <tvar|2> </> module.

How do I know which module and submodule to call?
The MediaWiki Action API is big, and extensions further enlarge it. Here are a few ways to work out your API request:

The [<tvar|1>https://www.mediawiki.org/w/api.php</> self-documenting API pages] contain a list of all modules and submodules with brief descriptions. You can start at the [<tvar|2>https://www.mediawiki.org/w/api.php</> main module] and follow the links to different submodules. (Append <tvar|3> </> to view the [<tvar|4>https://www.mediawiki.org/w/api.php?action=help&recursivesubmodules=1</> expanded version])
 * In the sidebar, look for the feature you wish to implement and follow the link for information about which modules to call.

Where can I find sample codes for using the API modules?
The 1>Special:MyLanguage/API:Main page</>|API documentation pages contain an 'Examples' section to demonstrate how different modules and submodules can be used. The [<tvar|2>https://www.mediawiki.org/w/api.php</> auto-generated docs] also have examples trailing the module descriptions.

See [<tvar|1>https://github.com/wikimedia/mediawiki-api-demos</> Mediawiki-API-demos] for code snippets in Python and JavaScript.

How can I control the output format?
The default output format is JSON. 1>Special:MyLanguage/API:Data formats#Output</>|Other output formats have been deprecated or removed in the 2>Special:MyLanguage/MediaWiki 1.33</>|latest stable MediaWiki version, and their use is discouraged.

In older versions, to control the output format, you can pass <tvar|1> </> in the query string.

For information, see 1>Special:MyLanguage/API:Data formats</>|API:Data formats.

Do I need an access token?
You will require an access token to perform data modifying actions like logging in, editing, moving pages, etc.

To learn more, refer to 1>Special:MyLanguage/API:Tokens</>|API:Tokens or the 2>Special:MyLanguage/Template:API</>|sidebar category 'Authentication'.

How can I make cross-site requests using the API?
You must use JSONP or CORS to make cross-site requests in MediaWiki.

For details, see 1>Special:MyLanguage/API:Cross-site requests</>|API:Cross-site requests.

Is there a limit to query results?
Yes, it depends on the query parameter. For example, the results for <tvar|1> </> and <tvar|2> </> queries cannot exceed 500 for regular users. The API pages contain information about these limits in the 'Additional notes' section or the 'Limits' section. Note that some modules impose stricter limits under certain conditions.

If you are unsure about what limit to set and just want as many results as possible, set the limit to <tvar|1> </>.

Is there a limit to API calls?
There is no concrete limit. Yet, we recommend making a reasonable number of calls to prevent getting blocked. If you want to make many requests, 1>#Where_can_I_get_more_help?</>|contact the administrators beforehand.

Also, see 1>Special:MyLanguage/API:Etiquette#Request limit</>| API:Etiquette.

Where can I get updates about the MediaWiki Action API?
You can subscribe to the [<tvar|1>https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce</> MediaWiki-API-Announce mailing list] for announcements and updates.

What are wiki dumps and how can I work with them?
1>:meta:Data_dumps</>|Wikimedia’s data dumps are dumps of wiki collections, content, metadata, search indices, etc. To work with dumps, see 2>:meta:Data_dumps#Using_and_re-using_the_dumps</>| using dumps and [<tvar|3>https://dumps.wikimedia.org/</> public dumps].

Where can I get more help?
If you can't find answers in the 1>Special:MyLanguage/API:Main page</>|MediaWiki API documentation or the [<tvar|2>https://www.mediawiki.org/w/api.php</> auto-generated documentation] pages, feel free to reach out in the following ways.


 * 1>Special:CreateAccount</>|Create a Wikimedia account (if you don't have one already) and add a new topic on the 2>API talk:Main page</>|API discussion page.
 * Ask your question on:
 * 1>Special:MyLanguage/MediaWiki on IRC</>|IRC in the <tvar|2></> channel on the Freenode network.
 * MediaWiki-API mailing list.

How can I create an API module in an extension?
1>Special:MyLanguage/API:Extensions</>|API:Extensions will walk you through the complete process of creating an API module in an extension.

What is the internal structure of the API?
1>Special:MyLanguage/API:Implementation Strategy</>|API:Implementation Strategy explains the implementation of the API machinery in 2>Special:MyLanguage/Core</>|MediaWiki Core.

How can I restrict the API usage?
To restrict the API usage, you can either restrict the use of write API or disable individual modules.

For instructions and examples, see 1>Special:MyLanguage/API:Restricting API usage</>|API:Restricting API usage.

How can I allow/restrict users from modifying the wiki content using the API?
In MediaWiki 1.14, users are allowed to modify the wiki content by default. To restrict, you have to set <tvar|1> </> in <tvar|2></>.

In MediaWiki 1.13 or earlier, you have to enable the write API with <tvar|1> </> to allow content modification.

For more information, see 1>Special:MyLanguage/API:Changing wiki content</>|API:Changing wiki content.

How do I detect an error?
If you encounter an error, the error response from the API will set the <tvar|1> </> HTTP header and return an 2>Special:MyLanguage/API:Errors and warnings#Legacy format</>|error structure.

What does this error mean?
Find your error in the 1>Special:MyLanguage/API:Errors and warnings#Standard error messages</>|list of standard error messages to understand what the error means.

How do I file a bug/feature requests?
You can report bugs and file feature requests on Wikimedia's task tracking tool, 1>Special:MyLanguage/Phabricator</>|Phabricator.

Note: Understand the 1>Special:MyLanguage/Phabricator/Help#Creating a task</>|task creation terms on Phabricator before proceeding.
 * Add the 1>phab:tag/mediawiki-api/</>| MediaWiki-API project tag to your task.
 * If your report/request is offered by an extension, add that extension's project. (e.g. <tvar|1> MediaWiki-extensions-AbuseFilter</>, <tvar|2> MediaWiki-extensions-FlaggedRevs</>, etc.)
 * Verify for duplicates before creating a new task.

See 1>Special:MyLanguage/How to report a bug</>| How to report a bug for more details.

Am I facing errors due to my API version?
If a website runs a different version of MediaWiki, it would also run a different version of the API. Some module parameters supported in one version might be deprecated (or removed) in others. Such parameters will throw an exception if used. The 1>Special:MyLanguage/API:Main page</>|API pages document any such deprecations.

See the 1>Special:MyLanguage/release notes</>|release notes for information regarding different API versions.