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).

Versioning
To ensure stable interfaces, extension endpoints should be versioned separately from the MediaWiki version and the MediaWiki REST API version. The extension API version should be included in the path in the format  where the version number is 0 or greater.


 * v0 indicates that the API is unstable and may change in backwards incompatible ways without notice.
 * v1 or greater indicates that the API is stable. Changes to API behavior are guaranteed to be backwards compatible within the same version. However, v1 or greater endpoints are not guaranteed to be backwards compatible with other versions.

Once the API is released as v1, increase the version if you need to make a backwards-incompatible change, such as:


 * Removing an endpoint
 * Removing or changing request or response properties

Additive changes to your API do not require a version increase, such as:


 * Adding an endpoint
 * Adding properties to request or response structures

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.