API:Extensions

Creating API modules in extensions
Extensions can add API modules. Create a new class that inherits  (for a top-level module), (for a non-generator submodule of action=query) or  (for a submodule of action=query with generator functionality) and implement at a minimum the methods ,  ,  , and.

In recent MediaWiki versions, only  may be required if you follow established naming conventions as described in .

Prefix
In the constructor of your API module, when you call  you can specify an optional prefix for your module's parameters. (In the generated documentation for a module this prefix, if any, appears in parentheses in the heading for the module.) If your module is a query submodule then you should give it a prefix, since a client can invoke multiple submodules each with its own parameters in a single request. If your module is a top-level action, then you may want to forgo a prefix.TODO:  is a counter-example, it uses the prefix   for its parameters.

Registration
When you've created your new class, you need to register it with the API by adding it to one of  (top-level modules, selected using action=),  (prop= modules),  (meta= modules) or  (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.

In MediaWiki 1.25 you can instead mention your API modules in  , for example:

It's possible to override core modules.

API class module names are capitalized similarly to  (e.g. ApiMassMessage, ApiQueryMMSites). The keys used for API module registration in  are capitalized similarly to   (e.g. APIListModules, APIPropModules, etc.). If you can't find your API module in the list at, check your capitalization.

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

For query submodules (subclasses of ApiQueryBase or ApiQueryGeneratorBase), instead override to allow ApiQuery to properly consider the needs of all executed submodules.

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. See documentation for, , and. For an example of how the latter is done, see.

Token handling
If your API module changes the wiki in any way, it should require a token of some kind. To have this handled automatically, implement the  method, returning the token that your module requires (probably the   edit token, but there are other tokens such as  ). The API base code will then automatically validate the token that clients provide in API requests in a (prefix-less)  parameter.

TODO there used to be  to return the token salt, now there's a rarely-overridden   method.

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

Conventions

 * enabled

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

Testing your extension

 * Visit [/api.php api.php] and navigate to the generated help for your module or query submodule. Your extension's help information should be correct.
 * 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  and interactively explore your API.
 * Visit <tvar|api></> 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 Special:MyLanguage/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  and adding to the end of LocalSettings.php:

SampleApiExtension.php
Starting with MediaWiki 1.25, you can instead register your API modules in extension.json under the keys 'APIModules', 'APIFormatModules', 'APIListModules', 'APIMetaModules', and 'APIPropModules'.

ApiSampleApiExtension.php
You can provide more information about your API by implementing the functions,   , and. Clients can make an API call to <tvar|api> </> to retrieve this information.

SampleApiExtension.i18n.php
since MediaWiki 1.23 the preferred Localisation file format is, and from MediaWiki 1.25 it is recommended to instead use messages for   in   and in