Wikibase REST API

Configuration

Enable the REST API

As of REL1_44, the Wikibase REST API is enabled when the Wikibase repo extension is loaded

To enable routes in development (not recommended for production use), also add:

$wgRestAPIAdditionalRouteFiles[] = 'extensions/Wikibase/repo/rest-api/routes.dev.json';

Enable Restful Search

Some REST API routes — particularly those related to Items and Properties search — require Elasticsearch to be configured and enabled through the CirrusSearch extensions.

If Elasticsearch is not set up, these routes will return an error response.

To enable Restfull search functionality:

• Install the WikibaseCirrusSearch, CirrusSearch, and Elastica extensions
• Add the necessary configuration to your LocalSettings.php

JSON structure changes

• Differences in the JSON data format between Wikibase REST API and ActionAPI

OpenAPI Specification

Our REST API specification is provided using an OpenAPI specification in the specs directory. The latest version is published on doc.wikimedia.org.

The specification can be "built" (i.e., compiled into a single JSON OpenAPI specs file) and validated using the provided npm scripts.

To modify API specs, install npm dependencies first, using a command like the following:

npm install

API specs can be validated using the npm test script, using a command like the following:

npm test

API specs can be bundled into a single file using the npm build:spec script, using a command like the following:

npm run build:spec

Autodocs can be generated from the API specification using the npm build:docs script, using a command like the following:

npm run build:docs

The base URL of the API can be configured by passing an API_URL environment variable:

API_URL='https://wikidata.org/w/rest.php' npm run build:docs

The autodocs and the bundled OpenAPI specification files are generated in the ../../docs/rest-api/ directory.

Versioning

• The interface of the REST API is versioned, not the OpenAPI schema document. This means that changes to the code and OpenAPI schema, that don't change the interface, are allowed without increasing the version.
• Versions will mostly follow the format described by SemVer 2.0.0. However, only MAJOR.MINOR versions, omitting .PATCH, will be created as we see little use for patch versions.
• The version of the REST API is recorded in the /info/version field of the OpenAPI schema.
• Changes for each version will be recorded in CHANGELOG.md.

Tests

Descriptions of the different kinds of tests can be found in the respective section of the directory structure overview above.

e2e and schema tests

These tests can be run with the command npm run api-testing.

The following needs to be correctly set up in order for all the tests to pass:

• the targeted wiki to act as both client and repo, so that Items can have sitelinks to pages on the same wiki
• a .api-testing.config file in repo/rest-api (next to this README.md file) - see the MediaWiki API integration tests docs
• the OAuth extension is installed and configured
• copy the X-Config-Override hack from Wikibase.ci.php to your LocalSettings.php. Do NOT do this on any sort of production wiki.