API:Extensions

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 ,,  , and. (In recent MediaWiki versions, the last three can omitted if you follow naming conventions; see API:Localisation.)

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:

The key you use in the wgApiXxModules array should be unique and is available to your code via  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, and you can enumerate images on specific pages (by specifying page titles) with. can also act as a generator, so you can "pipe" it to. By convention when a module acts as a generator its parameters, often the same as in its regular mode, are prefixed with ' '. 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.

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,   and   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:

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:

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. MediaWiki) as titles, you might use: 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, 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  parameter.

Returning results
Use  to return an array of information to the API caller. See the example at Manual:ApiResult.php. Pass your API module's name (available as ) as the second parameter so API results don't overlap.

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

Testing your extension

 * Visit [http:/api.php api.php], your extension's information should appear in its voluminous output
 * The example URLs you provided in  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 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  (i.e. an emoticon) as a parameter and outputs various data (viz. reply emoticons and predictions) in response. For example:

to generate: 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:

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