Wikibase REST API

Configuration

Enable the REST API

To enable the production-ready routes, add the following line to your LocalSettings.php file:

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

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

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

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:

docker run --rm --user $(id -u):$(id -g) -v $PWD:/app -w /app node:16 npm install

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

docker run --rm --user $(id -u):$(id -g) -v $PWD:/app -w /app node:16 npm test

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

docker run --rm --user $(id -u):$(id -g) -v $PWD:/app -w /app node:16 npm run build:spec

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

docker run --rm --user $(id -u):$(id -g) -v $PWD:/app -w /app node:16 npm run build:docs

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

Development

• Architecture Decision Records

Project structure

This REST API follows the Hexagonal Architecture approach and takes inspiration from an article about Netflix's use of the hexagonal architecture. This decision is documented in ADR 0001.

Directory structure

• docs/
  • adr/: Architectural Decision Records
• ../../docs/rest-api/: the built OpenAPI specification and swagger documentation
• specs/: OpenAPI specification source
• src/
  • DataAccess/: implementations of services that bind to persistent storage
  • Domain/: domain models and services
  • Presentation/: presenter and converter classes to manipulate the output as part of the transport layer
  • RouteHandlers/ classes that create and pass request DTO into use cases and return HTTP responses
  • UseCases/: one directory per use case
• tests/
  • mocha/: tests using the mocha framework
    • api-testing/: end-to-end tests using MediaWiki's api-testing library
    • openapi-validation/: tests against the OpenAPI spec
  • phpunit/: integration and unit tests using the phpunit framework

Tests

e2e and schema tests

These tests can be run with the command npm run api-testing. They require the targeted wiki to act as both client and repo, so that Items can have sitelinks to pages on the same wiki.