API:Tutorial

From MediaWiki.org
Jump to navigation Jump to search

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.

What is the MediaWiki Action API?[edit]

API:Main page is a good starting point for understanding the API. In a nutshell, MediaWiki Action API is a web service. There are many types of web services, and Action API’s type is REST, which is a more flexible and scalable protocol and mostly uses HTTP requests.

You can let your program talk to the API and get access to wiki features such as logging in to a wiki, creating and editing a page, searching for a title or text, parsing content, etc. This API is used by extension developers, wiki site administrators, and third-party developers.

On the right sidebar of this page, there are so many features listed in different categories that are supported by the API. Before exploring any of these features, read through the overview pages such as data formats, errors and warnings, the Action API FAQ, etc. listed on API:Main page to get an idea of the capabilities of API.

How to use it[edit]

You can request for data from client slide to the server over HTTP and get the response back in a standard format. A request consists of an endpoint and a set of parameters. There are two types of request that can be made: GET And POST. In case of a GET request, parameter would be a query string and in case of POST request, parameter would be data in JSON format.  

Request format[edit]

All Wikimedia Wikis have endpoints in this format http://example.org/w/api.php. To operate on MediaWiki or English Wikipedia, use the related endpoint. For testing, for example, to make a test edit or create an account, use the test wiki endpoint in your queries.

In the query string, one of the parameters would be action. As the name is; it tells the API which action to perform. One of the most popular action is query (action=query) that allows fetching data from a wiki. Following the action parameter, the next could be from one of the three query module types listed below:

  • prop: get properties of pages  
  • list: get list of pages matching a certain criterion
  • meta: get meta information about the wiki and user

Finally, include the format parameter telling the API in which format to get the results. Though the MediaWiki API has supported different parameters in the past, the most recommended format is JSON; always use JSON.

Request format
Request format









A simple query[edit]

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 Action API.

Let's search for a title in a wiki! Doing so would require the use of the search module documented on API:Search.

GET Request[edit]

To search for page titles matching Craig Noone GET Request would be:

It will contain:

  • http://en.wikipedia.org/w/api.php endpoint which is of English Wikipedia in this case
  • action=query to fetch data from wiki
  • list=search to get list of pages matching a criteria
  • srsearch= along with a page title to search for
  • format=jsonfm recommended format for output

Response[edit]

As a result, you will get a list of pages titles that match Craig Noone in JSON format:

{
    "batchcomplete": "",
    "continue": {
        "sroffset": 10,
        "continue": "-||"
    },
    "query": {
        "searchinfo": {
            "totalhits": 210
        },
        "search": [
            {
                "ns": 0,
                "title": "Craig Noone",
                "pageid": 18846922,
                "size": 22548,
                "wordcount": 1771,
                "snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
                "timestamp": "2018-11-02T22:25:45Z"
            },
            {
                "ns": 0,
                "title": "Noone",
                "pageid": 32906333,
                "size": 553,
                "wordcount": 64,
                "snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to:  <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
                "timestamp": "2015-08-16T05:16:17Z"
            }
            ...
        ]
    }
}

Examples of projects using Action API[edit]

Some example of projects in Wikimedia that use Action API:

  • 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 neat visualization that shows real time edits made on Wikipedia.

Additional notes[edit]

  • 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 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 API:Etiquette.
  • 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 API:Tokens to proceed further.

Resources[edit]