Date: 2023-02-01

Status

accepted

Context

At the time of writing, Wikibase REST API endpoints are not defined by default when loading the Wikibase extension. Endpoints are defined by developers configuring them in the routes.json file and Wikibase admins adding the file to the $wgRestAPIAdditionalRouteFiles mediawiki configuration variable. We also maintain an OpenAPI Definition of the Wikibase REST API which, among other things, is used to create visual and interactive documentation hosted on doc.wikimedia.org. During development, new endpoints need to be defined in the route file and OpenAPI Definition before they can be considered ready for use, as they need to be available on local instances, CI systems, and test systems (e.g. Beta Wikidata).

As well as configuring what endpoints are defined in mediawiki, a route file also configures which factory method (or handler class) should be used. This means a route file is coupled with the implementation. For example, renaming a factory would also require updating the route file to match. So, while you can enable multiple route files with $wgRestAPIAdditionalRouteFiles, it is not recommended to have the same endpoint configuration duplicated in multiple route files. In other words, the route file should not be used as a mechanism for Wikibase admins to configure which endpoints are defined.

We were concerned that deployers of the REST API would want control over what endpoints are defined. The stakeholders we spoke to aren't currently concerned about this and are happy for us to decide what endpoints are defined and when. There is also a desire from some stakeholders to have the same endpoints enabled across all Wikibase instances in order to provide consistent functionality.

REST API endpoints can also be defined by adding them to an extension's JSON configuration file (extension-repo.json in this case) under "RestRoutes" (see REST_API/Extensions#Defining_routes). This might be the best place for production-ready endpoints in the future, once the REST API is no longer 'v0' and considered stable, as they can be enabled by default when the Wikibase extension is loaded. WIP endpoints can still be enabled where needed (e.g. CI and test systems) via $wgRestAPIAdditionalRouteFiles.

How to manage new features or changes to existing endpoints are outside the scope of this ADR.

Decision

We will maintain two route files stored in the repo/rest-api directory of the Wikibase extension:
- routes.json that will contain routes completed to a functional state
- routes.dev.json that will contain WIP routes which is meant for local development, CI, and test systems
We will mark WIP routes in the OpenAPI Definition with a [WIP] prefix in the summary and This endpoint is currently in development and is not recommended for production use. in the description.
Wikibase admins should not create their own route files or modify the existing ones

Consequences

We have control over the route files and can update them at the same time if any factory methods change
The Wikibase REST API can still be enabled separately to the Wikibase extension
Wikibase admins can decide which route file(s) they want to enable via the $wgRestAPIAdditionalRouteFiles configuration option
All Wikibase instances that have enabled the REST API via the Wikibase/repo/rest-api/routes.json file will have the same routes available. Wikibase admins will have limited control over what routes are enabled and when. This is good for consistency across the Wikibase ecosystem.
Wikibase admins that create their own route file risk broken routes if our factories change.
We will be able to add new routes to the OpenAPI definition before they are ready, while still indicating the status of each route.