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 that defines a REST API endpoint accessible at.

RestRoutes configuration properties

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 Handler class. Handler provides accessors such as:


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

Handler subclasses should implement the execute function, which is called when the endpoint is invoked. See the generated MediaWiki documentation for accessors available to the Handler class.

For simpler parameter mapping, extend the SimpleHandler class, which derives from Handler. SimpleHandler unpacks parameters from the path template and passes them as formal parameters to run. SimpleHandler subclasses should implement run instead of execute. See the generated MediaWiki documentation for accessors available to SimpleHandler.

For example, here's a handler for a route that applies a text transformation to the  provided in the path.

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.