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 extension called RestApiExample 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. When organizing your extension, you can choose to group multiple handlers into a single file or to create one file per handler; handler files should be located within a /Handler directory. See the generated MediaWiki documentation for accessors available to handlers.

You can implement a new handler by extending 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.

For example, here's the handler used by the route defined by the RestApiExample extension, stored at RestApiExample/Handler/EchoPathParamHandler.php.

Parameter validation
fetches ParamValidator settings for parameters defined by the API route. Each parameter must specified with the PARAM_SOURCE ('path', 'query', or 'post'), the PARAM_TYPE, and PARAM_REQUIRED (true or false).

Here's an example defining two path parameters: title (a string) and type (one of a set of allowed strings specified by a 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.