Using the MediaWiki API

Explore the versatile MediaWiki API, capable of performing nearly all user interface functions and more. Our guide shows you how to effectively interact with your wiki's API.

Daniel Scherzer

Published on Tuesday, 27 June 2023

Share:

• 
• 
• 

Occasionally, you might prefer to engage with a wiki through programming rather than its user interface. Fortunately, MediaWiki offers a highly flexible API capable of performing nearly all actions available through the user interface, and sometimes even additional ones! In this guide, we'll show you several methods to interact with a wiki's API.

Note that MediaWiki provides two different API endpoints – the “action” API, and a separate REST API. This article deals with the action API only.

MediaWiki API Documentation

While the introduction below attempts to provide the basics of how to use the MediaWiki API, one of the great features of MediaWiki is that the API documentation is built in to the various API modules. On any MediaWiki wiki, going to `api.php` (instead of `index.php` for interacting with articles) should, if no other request is made, serve the default API documentation. For example, https://en.wikipedia.org/w/api.php provides documentation of the API on the English Wikipedia.

Furthermore, MediaWiki comes with a helpful special page, Special:ApiSandbox, which further eases learning and exploring the MediaWiki api by providing an easy interface to create and execute API requests.

Making a Request

The MediaWiki API requires some requests, specifically those that can change the wiki, to be submitted with an HTTP POST request, and for the rest GET can be used. The primary difference between the two is that in a POST request, the parameters are part of the request body and are not included in the URL, thus avoiding revealing authorization tokens. 

The query module is the primary way that data is fetched from a wiki. There are three different types of information that the module can provide, and each multiple different pieces of information can be retrieved in a single request, including multiple pieces of information with the same type.

"PROPs"

By default, if the query module is given one or more pages, it returns very basic information about them – the title, namespace, and page id. However, for each additional prop that is added, more information is included in the returned results.

For example, on the English Wikipedia, the main page is in namespace 0 and has page id 15580374. Thus, if no properties are requested for that title, the query is:

• https://en.wikipedia.org/w/api.php?action=query&titles=Main Page&format=json&formatversion=2

    { 
        "action": "query", 
        "titles": "Main Page", 
        "format": "json", 
        "formatversion": 2 
    }
 

And the result is:

• https://en.wikipedia.org/w/api.php?action=query&titles=Main%20Page&format=json&formatversion=2

    { 
        "batchcomplete": true, 
        "query": { 
            "pages": [ 
                { 
                    "pageid": 15580374, 
                    "ns": 0, 
                    "title": "Main Page", 
                } 
            ] 
         } 
     }

When the info property is requested (by adding the “prop”: “info” parameter), some more attributes are filled in – the page language, length, last edit, and more:

• https://en.wikipedia.org/w/api.php?action=query&titles=Main Page&prop=info&format=json&formatversion=2

    { 
        "batchcomplete": true, 
        "query": { 
            "pages": [ 
                { 
                    "pageid": 15580374, 
                    "ns": 0, 
                    "title": "Main Page", 
                    "contentmodel": "wikitext", 
                    "pagelanguage": "en", 
                    "pagelanguagehtmlcode": "en", 
                    "pagelanguagedir": "ltr", 
                    "touched": "2023-05-29T11:29:36Z", 
                    "lastrevid": 1114291180, 
                    "length": 2987
                } 
            ] 
         } 
     }

We can even get more detailed information by telling the info module to also include, for example, whether the page is protected, and if so how. By setting “inprop”: “protection” the result would include details about the protection of the page, for example.

Another common property that is requested for pages is the text of the latest revision (i.e. the current content). The revisions property can be requested with “prop”: “revisions”.

And, perhaps best of all, multiple properties can be requested at once! By default, the revisions property does not include the content of the page, just details about the latest edit. To fetch both general information about the main page, and details about the last edit, use “prop”: “info|revisions” which results in:

• https://en.wikipedia.org/w/api.php?action=query&titles=Main Page&prop=info|revisions&format=json&formatversion=2

    { 
        "batchcomplete": true, 
        "query": { 
            "pages": [ 
                { 
                    "pageid": 15580374, 
                    "ns": 0, 
                    "title": "Main Page", 
                    "contentmodel": "wikitext", 
                    "pagelanguage": "en", 
                    "pagelanguagehtmlcode": "en", 
                    "pagelanguagedir": "ltr", 
                    "touched": "2023-05-29T11:34:58Z", 
                    "lastrevid": 1114291180, 
                    "length": 2987, 
                    "revisions": [ 
                        { 
                            "revid": 1114291180, 
                            "parentid": 1114117152, 
                            "minor": false, 
                            "user": "The Blade of the Northern Lights", 
                            "timestamp": "2022-10-05T19:27:50Z", 
                            "comment": "Same issue, commented out text accidentally got split into two lines of markup"
                        } 
                    ] 
                } 
            ] 
        } 
    }

The revisions property added a new revisions key to the page object, while the info property added a few, such as pagelanguage and length. If we specify both properties, then both of the pieces of information are returned under the separate keys.

Furthermore, the overall pages object in the result is an array that holds information about each title that was requested. To also get the same information about Talk:Main Page, simply add that to the title parameter – multiple values are separated by a |, as shown with querying multiple properties of the main page above.

"LISTs"

The list module is used to retrieve a list of values, unrelated to a specific page that was submitted in the request. For example: 

• You can retrieve a list of all pages:
  • https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&format=json&list=allpages&formatversion=2
• All log events:
  • https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&format=json&list=logevents&formatversion=2
• All users:
  • https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&format=json&list=allusers&formatversion=2

"META"

The meta module is used to retrieve metadata about the overall site. For example, the siteinfo module returns general information about the MediaWiki installation, and userinfo module returns information about specific users. 

Note that the distinctions between list and meta are not set in stone. For example, wikisets might be more like other meta modules than a list, and the list of all messages might be more like a list module than a meta module. However, they are generally used the same.

Making an Edit

Making an edit is done using the (aptly-named) edit API module, the documentation for which can be found at https://en.wikipedia.org/w/api.php?action=help&modules=edit.

The basic requirements for an edit are:

1. a page to be editing,
2. a change to make, and
3. a token to authenticate the request

These tokens can be requested from the API, or when using the mw.Api utility, will be retrieved automatically when using the correct wrapper functions.

When making API requests from JavaScript that is executed directly on the wiki in question, the mw.Api ResourceLoader module is available to simplify making requests. See the documentation.

Conclusion

The MediaWiki Action API provides essentially all of the functionality that is available when using the web browser, and in same cases can even do things that the web browser cannot. The primary way to retrieve information about the site is using the query module, and most editing is done with the edit module. And, as with most parts of the MediaWiki interface, extensions can add custom handling and additional modules. Don’t hesitate to reach out to us if you want to add an extra API module for your wiki. We also have many other informative blogs you can check out here.