API development

API Development for MediaWiki: A Beginner's Guide

Introduction

Application Programming Interfaces (APIs) are fundamental to modern software development, and MediaWiki is no exception. An API allows different software systems to communicate with each other and exchange data. For MediaWiki, this means enabling external applications – from bots and mobile apps to custom extensions and integrations with other services – to interact with your wiki in a controlled and programmatic manner. This article provides a comprehensive introduction to API development for MediaWiki, geared towards beginners. We'll cover the core concepts, available APIs, authentication, common use cases, and practical examples. This knowledge will empower you to extend the functionality of your MediaWiki installation and create powerful, customized solutions. Understanding the API is crucial for anyone looking to move beyond basic wiki editing and truly leverage the platform’s potential. This article assumes basic familiarity with concepts like HTTP requests and data formats like JSON.

What is an API?

At its core, an API defines a set of rules and specifications that allow different software applications to interact. Think of it as a contract; it outlines what requests can be made, what data is expected, and what responses will be returned. Without APIs, every application would need to understand the internal workings of every other application, a clearly impractical scenario.

In the context of MediaWiki, the API provides a standardized way to:

**Read data:** Fetch articles, revisions, user information, category structure, and more.
**Write data:** Create, edit, and delete pages, upload files, and manage users.
**Perform actions:** Run maintenance tasks, search for content, and trigger specific wiki functions.

The MediaWiki API is primarily a RESTful API, meaning it utilizes standard HTTP methods (GET, POST, PUT, DELETE) to interact with resources. Data is commonly exchanged in JSON (JavaScript Object Notation) format, a lightweight and human-readable format that is easily parsed by most programming languages. Understanding JSON is therefore essential for working with the MediaWiki API.

Available APIs

MediaWiki offers several APIs, each serving different purposes:

**REST API:** The primary and most commonly used API. It provides a comprehensive set of endpoints for interacting with the wiki. This is what we'll focus on primarily in this article. It's designed for ease of use and integration with various client applications.
**Action API:** A legacy API that predates the REST API. While still available, it’s generally recommended to use the REST API for new development due to its improved design and features. It's still useful for understanding older extensions or scripts that may rely on it.
**GraphQL API:** Introduced more recently, the GraphQL API offers a more flexible and efficient way to query data. It allows clients to request only the specific data they need, reducing network overhead. However, it requires more setup and knowledge.
**OAuth 2.0:** While not an API itself, OAuth 2.0 is a crucial authentication protocol used to securely access the MediaWiki API on behalf of users, enabling applications to act on their behalf without requiring their passwords. OAuth 2.0 is critical for building secure integrations.

For most beginner projects, the **REST API** will be the best starting point.

Authentication

Accessing the MediaWiki API often requires authentication, particularly for write operations (editing, creating pages, etc.). Different authentication methods are available:

**User and Password:** The simplest method, but generally discouraged for security reasons. It involves sending your username and password with each request.
**Cookies:** If you’re already logged in to the wiki in your browser, you can use cookies to authenticate API requests. This is convenient for testing but not suitable for automated applications.
**API Tokens:** A more secure method. You generate a unique token that identifies your application and grants it specific permissions. Tokens can be configured with various restrictions, limiting the scope of access. API Tokens are the recommended approach for most applications.
**OAuth 2.0:** The most secure and robust method, especially for applications that need to access user data on their behalf. It involves a more complex setup process but provides the highest level of security and control.

To obtain an API token, you can use the `api:token` action (via the REST API or Action API). The token should be included in your API requests as a parameter (e.g., `&token=YOUR_TOKEN`). Always store API tokens securely and avoid hardcoding them directly into your code.

Common Use Cases

The MediaWiki API opens up a wide range of possibilities. Here are some common use cases:

**Bot Development:** Create bots to automate tasks such as fixing typos, adding categories, or monitoring changes. Bots are extremely useful for wiki maintenance.
**Mobile App Integration:** Develop mobile apps that allow users to access and edit wiki content on their smartphones or tablets.
**Data Integration:** Integrate MediaWiki with other systems, such as databases, content management systems, or CRM platforms.
**Custom Extensions:** Build custom extensions that add new features and functionality to your wiki.
**Automated Content Generation:** Automatically generate wiki pages based on external data sources.
**Reporting and Analytics:** Extract data from the wiki for reporting and analysis purposes. Analyzing wiki data can reveal valuable insights into user behavior and content performance.
**Content Migration:** Migrate content from other platforms into MediaWiki.
**Search Enhancement:** Build custom search interfaces or enhance the existing search functionality. Improving Search is often a key goal for wiki administrators.

Making API Requests

You can make API requests using various tools and programming languages. Here are some popular options:

**cURL:** A command-line tool for making HTTP requests. Useful for testing and scripting.
**PHP:** A server-side scripting language commonly used with MediaWiki.
**Python:** A versatile programming language with excellent libraries for working with APIs. Python is a popular choice for bot development and data analysis.
**JavaScript:** A client-side scripting language used for web development. Useful for making API requests from within a web browser.

The basic structure of a REST API request is as follows:

``` https://your-wiki-url/w/api.php ?action=query &format=json &title=Main_Page &prop=revisions &rvprop=content &token=YOUR_TOKEN ```

Let's break down this example:

`https://your-wiki-url/w/api.php`: The base URL of the MediaWiki API. Replace `your-wiki-url` with the actual URL of your wiki.
`action=query`: Specifies the action to perform (in this case, querying data).
`format=json`: Specifies the desired response format (JSON).
`title=Main_Page`: Specifies the title of the page to query.
`prop=revisions`: Specifies the properties to retrieve (in this case, revisions).
`rvprop=content`: Specifies the revision properties to retrieve (in this case, the content of the revision).
`token=YOUR_TOKEN`: Your API token for authentication.

The API will return a JSON response containing the requested data. You'll need to parse this JSON response using your chosen programming language to access the data.

Example: Retrieving Page Content

Here's a Python example of retrieving the content of the "Main Page" using the MediaWiki API:

```python import requests import json

WIKI_URL = "https://your-wiki-url/w" API_TOKEN = "YOUR_TOKEN"

def get_page_content(title):

   params = {
       'action': 'query',
       'format': 'json',
       'title': title,
       'prop': 'revisions',
       'rvprop': 'content',
       'token': API_TOKEN
   }

   response = requests.get(f"{WIKI_URL}/api.php", params=params)
   response.raise_for_status()  # Raise an exception for bad status codes

   data = response.json()
   try:
       content = data['query']['pages']['-1']['revisions'][0]['content']
       return content
   except (KeyError, IndexError):
       return None

if __name__ == "__main__":

   page_title = "Main Page"
   content = get_page_content(page_title)

   if content:
       print(f"Content of '{page_title}':\n{content}")
   else:
       print(f"Could not retrieve content for '{page_title}'.")

```

Remember to replace `https://your-wiki-url/w` and `YOUR_TOKEN` with your actual wiki URL and API token.

Error Handling

API requests can sometimes fail due to various reasons, such as invalid parameters, authentication errors, or server issues. It's crucial to implement proper error handling in your code. The MediaWiki API returns error codes and messages in the JSON response. Check the `error` key in the JSON response to identify the error and handle it accordingly. Common error codes include:

`badtoken`: Invalid API token.
`missingtitle`: The specified title does not exist.
`paramerror`: An invalid parameter was specified.
`readonly`: The wiki is in read-only mode.

Advanced Topics

**Modules:** MediaWiki's API is structured around modules. Learning to leverage different modules like `categorymembers`, `images`, and `usercontribs` expands your API capabilities.
**Lists:** The API supports listing results (e.g., listing all pages in a category). Pay attention to `cmcontinue` and `continue` parameters for paginating through large result sets.
**Batch Requests:** For efficiency, you can make multiple API requests in a single batch. This reduces the overhead of establishing multiple connections.
**Rate Limiting:** Be mindful of rate limits imposed by the MediaWiki API. Exceeding the rate limit can result in your requests being blocked.
**Utilizing Variables and Parameters effectively.**
**Understanding Templates and how they relate to API data extraction.**
**Leveraging Extension functionality for enhanced API access.**

Resources

**MediaWiki API Documentation:** [1]
**Action API Documentation:** [2]
**REST API Documentation:** [3]
**OAuth 2.0 Documentation:** [4]
**cURL Documentation:** [5]
**Python Requests Library:** [6]
**JSON Documentation:** [7]

Conclusion

The MediaWiki API provides a powerful and flexible way to extend the functionality of your wiki. By understanding the core concepts, available APIs, authentication methods, and common use cases, you can build custom solutions that meet your specific needs. Start with the REST API, experiment with the examples provided, and consult the official documentation for more detailed information. With a little practice, you'll be well on your way to mastering MediaWiki API development.

Main Page Help:API Manual:API Extension:API MediaWiki PHP JSON OAuth 2.0 Bots Search Templates Variables Extension

Start Trading Now

Sign up at IQ Option (Minimum deposit $10) Open an account at Pocket Option (Minimum deposit $5)

Join Our Community

Subscribe to our Telegram channel @strategybin to receive: ✓ Daily trading signals ✓ Exclusive strategy analysis ✓ Market trend alerts ✓ Educational materials for beginners