API:Tutorial

In this tutorial, you will learn about the MediaWiki Action API, how to use it, request format, a simple query, and examples of projects using Action API.

Browse demo apps on Toolforge

Overview of the MediaWiki Action API
The MediaWiki Action API is a RESTful web service that allows users to perform certain wiki-actions like page creation, authentication, parsing, searching, etc. is a good starting point for understanding the API.

Your program sends requests to the API to get access to wiki features. For example, log in to a wiki, create and edit a page, search for a title, search for content text, or parse content. The Action API is available for third-party developers, Wikimedia extension developers, and wiki site administrators.

On the right sidebar of this page, there are many features that are supported by the API, grouped by category. Before sending requests to a wiki server, first read through the overview pages such as data formats, errors and warnings, and the Action API FAQ.

How to use the MediaWiki Action API
You can request for data from client side to the server over HTTP and get the response back in a standard format (typically JSON). A request consists of an endpoint and a set of parameters. There are two types of request that can be made: GET and POST. For a GET request, a parameter would contain a query string in the URL. For a POST request, format the parameters in JSON format.

Request format
All Wikimedia Wikis have endpoints in this format. To operate on the MediaWiki main site or English Wikipedia, use the related endpoint. For example, the English Wikipedia is at For testing new accounts or test edits to pages, use the test wiki endpoint.

In the query string in the URL, add the parameter. It tells the API which action to perform. The most popular action is (the URL would contain ), which allows fetching data from a wiki. Following the parameter, add another parameter to indicate which one of the three query module types you want to perform:


 * - get properties of pages
 * - get list of pages matching a certain criterion
 * - get meta information about the wiki and user

Finally, include the parameter, which tells the API in which format to get the results. The recommended format is JSON. The API has supported other output formats in the past, but they are not generally recommended.

A simple query
Let’s take an example of a simple query to understand what a typical GET request and response would look like in the context of the Action API.

Let's search for a title in a wiki. We will use the module documented on.

GET request
To search for page titles or content matching, the URL for the HTTP GET request would be:  Explanation of each part of the URL:


 * is the main endpoint. In this case it is English Wikipedia.
 * means fetch data from wiki.
 * means get list of pages matching a criteria.
 * indicates the page title or content to search for. The indicates a space character in a URL.
 * indicates JSON output, which is the recommended output format.

Response
The response is a JSON format document with a list of pages titles that match Craig Noone:

Examples of projects using Action API
Some example of projects in Wikimedia that use Action API:


 * [ https://upload.wikimedia.org/wikipedia/commons/a/af/Screenshot_of_Wikipedia_IOS_app.jpg Wikipedia iOS App], in which one of the features is to search for wiki pages near your location.
 * Bots that operate on a wiki. Pywikibot is a bot framework written in Python that interfaces with MediaWiki API which a lot of bot developers use.
 * API use in visualizing data obtained from a wiki. Such as this [ http://listen.hatnote.com/ neat visualization] that shows real time edits made on Wikipedia.

Additional notes

 * Several sites are using MediaWiki. They might all be running a different version of MediaWiki and in turn the API. Some module parameters supported in one version might be deprecated or removed in others. You could learn about that in each module's documentation via [ https://www.mediawiki.org/w/api.php?action=help API help module].
 * If you want to make a lot of API calls, and perhaps run very busy and active bots, talk to wiki admins ahead of time, so they do not block you. See list of Administrators of Wikimedia projects. Read more about this topic on.
 * All data modifying actions such as logging, editing or moving a page, and watching or patrolling changes would require tokens. You would need to obtain tokens via to proceed further.

Resources

 * Use Special:APISandbox to experiment with the Action API. You can play around with supported actions, specify a value for parameters, and send requests to the API to see the results on the same page.
 * [ http://dumps.wikimedia.org/ Wikimedia dumps] so you can work with them locally.
 * Read through tutorials: [ https://restful.io/an-introduction-to-api-s-cee90581ca1b An Introduction to API's] and [ https://medium.com/extend/what-is-rest-a-simple-explanation-for-beginners-part-1-introduction-b4a072f8740f What is REST — A Simple Explanation for Beginners].
 * [ https://www.mediawiki.org/w/api.php?action=help MediaWiki API help] provides auto-generated API documentation of all supported modules.
 * provides an overview of the Action API.
 * [ https://upload.wikimedia.org/wikipedia/commons/4/48/The_MediaWiki_Web_API_and_How_to_use_it_-_San_Francisco_Wikipedia_Hackathon_2012.ogv Introduction to the MediaWiki API] by User:Roan_Kattouw_(WMF) at the San Francisco Hackathon, 2012. This tutorial guide goes along with the video.
 * GitHub: [ https://github.com/wikimedia/mediawiki-api-demos MediaWiki API Demos]