API:REST API/Extensions

The MediaWiki REST API allows you to access wiki content and functionality through a RESTful, HTTP interface. MediaWiki extensions can build on the REST API to surface their own extension-specific endpoints. The REST API extension interface is available in MediaWiki 1.34 and later.

Defining routes
An extension can define REST API endpoints in its  file under the   scope. is an array of objects, each representing a unique API path. Here's an example of an  file for an example extension that defines a REST API endpoint accessible at.

In this example,  is assigned as the handler class for requests to this endpoint. We'll discuss handling requests in the next section.

Handling requests
Within MediaWiki, a handler is a code unit responsible for accepting HTTP requests to a given route and returning a response. It is recommended to store handler files within a /Handler directory.

To implement a new handler, you can extend the base Handler class or, for simpler parameter mapping, extend the SimpleHandler class. SimpleHandler unpacks parameters from the path template and passes them as formal parameters to. must be declared in the subclass; it cannot be declared as abstract because it has a variable parameter list. SimpleHandler provides accessors such as:


 * getRequest: Returns the RequestInterface object.
 * getConfig: Returns the configuration array for the current route, decoded from JSON.
 * getResponseFactory: Returns a ResponseFactory object containing a variety of convenient factory functions for creating a response object.

See the generated MediaWiki documentation for all accessors available to SimpleHandler.

For more control over parameters, you can extend the base Handler class directly instead of using SimpleHandler. Handlers extended from the base Handler class are called used the abstract execute function. See the generated MediaWiki documentation for accessors available to Handler.

For example, here's the handler used by the route defined by the example extension, stored at mediawiki-extensions-examples/includes/RestApiExample.php.

Parameter validation
getParamSettings fetches ParamValidator settings for parameters defined by the API route. Each parameter must be specified with the PARAM_SOURCE ('path', 'query', or 'post'), the PARAM_TYPE, and PARAM_REQUIRED (true or false). The example above defines two path parameters:  (a string) and   (one of a set of allowed strings specified by the   constant).

Documenting endpoints
Endpoints provided by an extension should be documented on the extension's main wiki page. See the extension REST API template to get started.