API:Extensions

Extensions:

Development

Tag Extensions

Parser Functions

Hooks

Special Pages

Skins

Magic Words

API

This page is part of the MediaWiki API documentation.

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • Etiquette and usage limits
• Tutorial
• Formats
• Error reporting
• Restricting usage
• Cross-site requests
• Authentication
  • Login
  • Logout
  • Account creation
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Parsing wikitext and expanding templates
• Purging pages' caches
• Parameter information
• Changing wiki content
  • Create and edit pages
  • Move pages
  • Rollback
  • Delete pages
  • Restore deleted revisions
  • (Un)protect pages
  • (Un)block users
  • (Un)watch pages
  • Mark revisions of watched pages as visited
  • Send email
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
  • Tokens
  • Page language
• Watchlist feed
• Wikidata
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code
• Asserting

Creating API modules in extensions

Extensions can add API modules. Create a new class that inherits ApiBase (for a top-level module), ApiQueryBase (for a non-generator submodule of action=query) or ApiQueryGeneratorBase (for a submodule of action=query with generator functionality) and implement at a minimum the methods execute(), getAllowedParams(), getParamDescription(), and getDescription().

When you've created your new class, you need to register it with the API by adding it to $wgAPIModules (top-level modules, selected using action=), $wgAPIPropModules (prop= modules), $wgAPIMetaModules (meta= modules) or $wgAPIListModules (list= modules), like this:

 // Register the ApiMyExt class as handler for action=myext
$wgAPIModules['myext'] = 'ApiMyExt';

The key you use in the wgApiXxModules array should be unique and is available to your code via $this->getModuleName() to pass back unique values in the API results structure.

It's possible to override core modules.

Generator modules

A generator module is somewhat like UNIX piping, where the output of one module is the input of another. For example: You can ask for a list of all pages with list=allpages, and you can enumerate images on specific pages (by specifying page titles) with prop=images. allpages can also act as a generator, so you can "pipe" it to prop=images. By convention when a module acts as a generator its parameters, often the same as in its regular mode, are prefixed with 'g'. Thus api.php?action=query&generator=allpages&gaplimit=8&prop=images&imlimit=15 generates a list of the first 8 wiki pages, and from them shows up to 12 images in total. Generator modules also need to implement executeGenerator().

Extending core modules

Since MediaWiki 1.14, it's possible to extend core modules' functionality using the following hooks:

• APIGetAllowedParams to add or modify the module's parameter list
• APIGetParamDescription to add or modify the module's parameter descriptions
• APIAfterExecute to do something after the module has been executed (but before the result has been output)
  • Use APIQueryAfterExecute for prop=, list= and meta= modules
    • If the module is run in generator mode, APIQueryGeneratorAfterExecute will be called instead

List of extensions with API functionality

See API extensions for examples of extensions that add or extend to the API.

Caching

By default ApiMain leaves caching of API calls up to the callee ('Cache-Control: private')! To modify this behavior for high volume requests add the following somewhere in your execute() method:

// Tell squids to cache
$this->getMain()->setCacheMode( 'public' );
// Set the squid & private cache time in seconds
$this->getMain()->setCacheMaxAge( 300 );

Returning errors

Some errors will be automatically generated if certain conditions that you set up are not met; for example, if the user fails to provide a title, then the "missingparam" error will be thrown if you have set getAllowedParams as follows:

// Title parameter.
public function getAllowedParams() {
	return array(
		'title' => array (
			ApiBase::PARAM_TYPE => 'string',
			ApiBase::PARAM_REQUIRED => true
		),
	);
}

Sometimes the types of error conditions set up by the methods supplied by ApiBase will not suffice and you will have to set up your own conditions. E.g., if you wanted to prevent the client from using interwiki links (e.g. wikiquote:MediaWiki) as titles, you might use:

$pageObj = $this->getTitleOrPageId( $params );
$titleObj = $pageObj->getTitle();
if ( $titleObj->isExternal() ) {
	$this->dieUsageMsg( array( 'invalidtitle', $params['title'] ) );
}

That would throw the error defined in messageMap. See documentation for ApiBase::dieUsage, ApiBase::dieUsageMsg, and ApiBase::getPossibleErrors. For an example of how the latter is done, see ApiEditPage::getPossibleErrors.

Edit token

If your API module changes the wiki in any way, it should require an edit token. To have this handled automatically, implement needsToken() to return true, and implement getTokenSalt() to return the token salt (or an empty string if there is none). Your API should receive the user token via the token parameter.

Returning results

use $this->getResult()->addValue() to return an array of information to the API caller, see the example at Manual:ApiResult.php#Example. You ordinarily pass your API module's name (available as $this->getModuleName()) as the second parameter to so API results don't overlap.

Conventions

enabled

The presence of a key enabled (e.g. with value '') means true, absence means false.

Testing your extension

• Visit api.php , your extension's information should appear in its voluminous output
  • The example URLs you provided in getExamples() should appear under "Examples", try clicking them.
  • Omit and mangle URL parameters in the query string, check your extension's response.
• Install Extension:ApiSandbox and interactively explore your API.
• Visit

api.php?action=paraminfo&modules=myext

to see additional information about your extension.

Sample API extension

An extension providing an API shares much setup code with other kinds of extensions; see Manual:Developing extensions for general information.

This is an example API extension that receives face (i.e. an emoticon) as a parameter and outputs various data (viz. reply emoticons and predictions) in response. For example:

api.php ? action=apisampleoutput & face=O_o & format=xml

to generate:

<api>
  <apisampleoutput apiresponses="are as follows">
    <nonverbalresponse emoticon="o_O"/>
    <predictions yourweek="You will learn something interesting and useful about API extensions this week"
      yourlife="You will become a successful MediaWiki hacker, which will serve you well in your life"
      eternity="Eventually all life will be destroyed in the heat death"/>
  </apisampleoutput>
</api>

To install it requires the usual procedure, i.e. copying the following three files into $IP/extensions/SampleApiExtension and adding to the end of LocalSettings.php:

require_once("$IP/extensions/SampleApiExtension/SampleApiExtension.php");

SampleApiExtension.php

<?php
 
// Take credit for your work, in the "api" category.
$wgExtensionCredits['api'][] = array(
 
   'path' => __FILE__,
 
   // The name of the extension, which will appear on Special:Version.
   'name' => 'Sample API Function',
 
   // A description of the extension, which will appear on Special:Version.
   'description' => 'A simple sample API extension',
 
   // Alternatively, you can specify a message key for the description.
   'descriptionmsg' => 'sampleapiextension-desc',
 
   // The version of the extension, which will appear on Special:Version.
   // This can be a number or a string.
   'version' => 1, 
 
   // Your name, which will appear on Special:Version.
   'author' => 'Me',
 
   // The URL to a wiki page/web page with information about the extension,
   // which will appear on Special:Version.
   'url' => 'https://www.mediawiki.org/wiki/API:Extensions',
 
);
 
// Map class name to filename for autoloading
$wgAutoloadClasses['ApiSample'] = __DIR__ . '/ApiSampleApiExtension.php';
 
// Map module name to class name
$wgAPIModules['apisampleoutput'] = 'ApiSample';
 
// Load the internationalization file
$wgExtensionMessagesFiles['myextension'] = __DIR__ . '/SampleApiExtension.i18n.php';
 
// Return true so that MediaWiki continues to load extensions.
return true;

ApiSampleApiExtension.php

<?php
class ApiSample extends ApiBase {
    public function execute() {
        // Get specific parameters
        // Using ApiMain::getVal makes a record of the fact that we've
        // used all the allowed parameters. Not doing this would add a
        // warning ("Unrecognized parameter") to the returned data.
        // If the warning doesn't bother you, you can use 
        // $params = $this->extractRequestParams();
        // to get all parameters as an associative array (e. g. $params[ 'face' ])
        $face = $this->getMain()->getVal('face');
 
        // Default response is a wink ;)
        $emoticon = ';)';
        $result = $this->getResult();
        // Other responses depend on the value of the face parameter
        switch ( $face ) {
            case 'O_o':
                $emoticon = 'o_O';
                break;
            case 'o_O':
                $emoticon = 'O_o';
                break;
        }
        // Top level
        $this->getResult()->addValue( null, $this->getModuleName(), array ( 'apiresponses' => 'are as follows' ) );
        // Deliver a facial expression in reply
        $this->getResult()->addValue( null, $this->getModuleName()
            , array ( 'nonverbalresponse' => array ( 'emoticon' => $emoticon ) ) );
        // Offer a few predictions about the user's future
        $this->getResult()->addValue( null, $this->getModuleName()
            , array ( 'predictions' => array (
                'yourweek' => 'You will learn something interesting and useful about API extensions '
                    .'this week' ,
                'yourlife' => 'You will become a successful MediaWiki hacker, which will serve you well '
                    .'in your life' ,
                'eternity' => 'Eventually all life will be destroyed in the heat death' ) ) );
        return true;
    }
 
    // Description
    public function getDescription() {
         return 'Get both nonverbal and verbal responses to your input.';
     }
 
    // Face parameter.
    public function getAllowedParams() {
        return array_merge( parent::getAllowedParams(), array(
            'face' => array (
                ApiBase::PARAM_TYPE => 'string',
                ApiBase::PARAM_REQUIRED => true
            ),
        ) );
    }
 
    // Describe the parameter
    public function getParamDescription() {
        return array_merge( parent::getParamDescription(), array(
            'face' => 'The face you want to make to the API (e.g. o_O)'
        ) );
    }
 
     // Get examples
     public function getExamples() {
         return array(
             'api.php?action=apisampleoutput&face=O_o&format=xml'
             => 'Get a sideways look (and the usual predictions)'
         );
    }
}

You can provide more information about your API by implementing the functions getResultProperties(), getPossibleErrors(), and getHelpUrls(). Clients can make an API call to api.php?action=paraminfo&module=apisampleoutput to retrieve this information.

SampleApiExtension.i18n.php

<?php
$messages = array();
$messages['en'] = array(
        'sampleapiextension-desc' => "This extension implements an apisampleoutput API module to provide, in response to "
        ."input the user provides in the 'face' field, an emoticon and some plausible predictions. For example, try "
        ."api.php?action=apisampleoutput&face=O_o&format=xml . For more information, see api.php",
);