This page is part of theMediaWiki Action API documentation.

This document covers creating an API module in an extension for use with MediaWiki 1.30 and later.

All API modules are subclasses ofApiBase, but some types of modules use a derived base class.The method of registration also depends on the module type.

action modules

Modules that provide a value for the mainaction parameter should subclassApiBase. They should be registered inextension.json using theAPIModules key.

format modules

Modules that provide a value for the mainformat parameter should subclassApiFormatBase. They should be registered inextension.json using theAPIFormatModules key. It's very uncommon for an extension to need to add a format module.

query submodules

Modules that provide a value for theprop,list, ormeta parameters toaction=query should subclassApiQueryBase (if not usable as a generator) orApiQueryGeneratorBase (if usable as a generator). They should be registered inextension.json using theAPIPropModules,APIListModules, orAPIMetaModules key.

In all cases, the value for the registration key is an object with the module name (i.e. the value for the parameter) as the key and the class name as the value.Modules may also be registered conditionally using theApiMain::moduleManager (for action and format modules) andApiQuery::moduleManager (for query submodules) hooks.

In the constructor of your API module, when you callparent::__construct() 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 a prefix is required, since a client can invoke multiple submodules each with its own parameters in a single request.For action and format modules, the prefix is optional.

Most modules require parameters.These are defined by implementinggetAllowedParams().The return value is an associative array where keys are the (unprefixed) parameter names and values are either the scalar default value for the parameter or an array defining the properties of the parameter using thePARAM_* constants defined byApiBase.

The example illustrates the syntax and some of the more commonPARAM_* constants.

protectedfunctiongetAllowedParams(){return[// An optional parameter with a default value'simple'=>'value',// A required parameter'required'=>[ApiBase::PARAM_TYPE=>'string',ApiBase::PARAM_REQUIRED=>true,],// A parameter accepting multiple values from a list'variable'=>[// The default set of valuesApiBase::PARAM_DFLT=>'foo|bar|baz',// All possible valuesApiBase::PARAM_TYPE=>['foo','bar','baz','quux','fred','blah'],// Indicate that multiple values are acceptedApiBase::PARAM_ISMULTI=>true,// Use standard "per value" documentation messagesApiBase::PARAM_HELP_MSG_PER_VALUE=>[],],// A standard "limit" parameter. It's generally best not to vary from this standard.'limit'=>[ApiBase::PARAM_DFLT=>10,ApiBase::PARAM_TYPE=>'limit',ApiBase::PARAM_MIN=>1,ApiBase::PARAM_MAX=>ApiBase::LIMIT_BIG1,ApiBase::PARAM_MAX2=>ApiBase::LIMIT_BIG2,],];}

Parameters are documented using MediaWiki's i18n mechanism. See#Documentation for details.

The code actually implementing the module goes in theexecute() method.This code will generally use$this→extractRequestParams() to get the input parameters, and will use$this→getResult() to get theApiResult object to add any output to.

Query prop submodules should use$this→getPageSet() to access the set of pages to operate on.

Query submodules that can be used as generators will also need to implementexecuteGenerator() which is passed andApiPageSet that should be filled with the generated pages.In this case, theApiResult should generallynot be used.

By default API responses are marked as not cacheable ('Cache-Control: private')!For action modules, you can allow caching by calling$this→getMain()→setCacheMode().This still requires clients pass themaxage orsmaxage parameters to actually enable caching.You can force caching by also calling$this→getMain()→setCacheMaxAge().

For query modules,do not call those methods.You can allow caching by instead implementinggetCacheMode().

In either case, be sure that private data is not exposed.

If your action module changes the wiki in any way, it should require atoken of some kind.To have this handled automatically, implement theneedsToken() method, returning the token that your module requires (probably the'csrf'edit token).The API base code will then automatically validate the token that clients provide in API requests in atoken parameter.

If you don't want to use a token that is part of core, but rather a custom token with your own permission checks, useApiQueryTokensRegisterTypes hook to register your token.

If your module accesses the primary database, it should implement theisWriteMode() method to returntrue.

ApiBase includes several methods for performing various checks, for example,

• If you need to assert that exactly one of a set of parameters was supplied, use$this→requireOnlyOneParameter().
• If you need to assert that at most one of a set of parameters was supplied, use$this→requireMaxOneParameter().
• If you need to assert that at least one of a set of parameters was supplied, use$this→requireAtLeastOneParameter().
• If you need to assert that the user has certain rights, use$this→checkUserRightsAny().
• If you need to assert that the user can take an action on a particular page, use$this→checkTitleUserPermissions().
• If the user is blocked (and that matters to your module), pass theBlock object to$this→dieBlocked().

But you will often run into cases where you need to raise an error of your own.The usual way to do that is to call$this→dieWithError(), although if you have aStatusValue with the error information you could pass it to$this→dieStatus() instead.

If you need to issue a warning rather than an error, use$this→addWarning() or$this→addDeprecation() if it's a deprecation warning.

The API is documented using MediaWiki's i18n mechanism.Needed messages generally have default names based on the module's "path".For action and format modules, the path is the same as the module's name used during registration.For query submodules, it's the name prefixed with query+.

Every module will need aapihelp-$path-summary message, which should be a one-line description of the module.If additional help text is needed,apihelp-$path-extended-description may be created as well.Each parameter will need aapihelp-$path-param-$name message, and parameters usingPARAM_HELP_MSG_PER_VALUE will also need aapihelp-$path-paramvalue-$name-$value for each value.

More details on API documentation are available atAPI:Localisation.

Extensions may also document their extra API modules on mediawiki.org.This should be located on the extension's main page or, if more space is required, on pages namedExtension:<ExtensionName>/API or subpages thereof (e.g.CentralAuth,MassMessage, orStructuredDiscussions).The API namespace is reserved for the API of MediaWiki core.

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
• APIGetParamDescriptionMessages - 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)
  • UseAPIQueryAfterExecute forprop=,list= andmeta= modules
    • If the module is run in generator mode,APIQueryGeneratorAfterExecute will be called instead

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

• Visitapi.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 ingetExamplesMessages() should appear under "Examples", try clicking them.
  • Omit and mangle URL parameters in the query string, check your extension's response.
• VisitSpecial:ApiSandbox and interactively explore your API.
• To see additional information about your extension:

• MediaWiki action API
• Extension creation