User:DKinzler (WMF)/Modular REST API

This document is a proposal to introduce the concept of component APIs [name TBD] into MediaWiki's REST framework. The goal is to provide better coesion of related entry points while avoding dependencies across teams.

Summary
Per this proposal, endpoints exposed by MediaWIki core would become available under a handfull of different prefixes, instead of all being exposed under.

The idea is that we group together sets of related REST endpoints that belong to the same business domain (or bounded context). Each such grouping forms a component API [name TBD] that has its own OpenAPI spec, is owned by a single team, and cen be versioned independently of other component APIs.

We have already been following this approach for extensions, using the convention that each extension should use a dedicated prefix for their API endpoints: E.g. CheckUser uses, OAuth uses  , etc. However, all the endpoints exposed by MediaWiki are exposed under the shared   prefix, even if they are entirely unrelated. And extensions are free to add endpoints under that prefix as well, making it difficult for clients to understand which endpoints they can expect to be available on every wiki.

With the new system, MediaWiki core would expose endpoints under several prefixes like  [or , TBD], so we would use   instead of. For each component API, a dedicated file would define the routes and may also contain or reference JSON schemas descibing the data structures used to interact with the entry points.Currently, all core routes are listed in a single file,, which has no support for schemas or meta-data.

Implementation
Currently, there is a single Router object in MediaWiki's REST framweork that determins which Handler to use to respond to an incoming request, based on the requested path (aka the request URI). The mapping from paths to Handlers is maintained in the coreRoutes.json file (as well as the coreDevelopmentRoutes.json file, for experimental routes not enabled in production). Extensions can add their own routes using an RestRoutes entry in extension.json, or by adding to the RestAPIAdditionalRouteFiles configuration variable''. Each r''oute files contain a list of route definition objects, which includes that path pattern and the handler class, among other things. All route files are loaded and processed, and the resulting data structure is cached so we don't have to load all these files on every request. The Router object operates on the cached data structure.

This way, MediaWiki core and any extension is free to define routes with any path patter. Shared prefixes are used for related endpoints per convention, but are not enforced. Similarly, version identifiers can be included in the paths, but are not requried or enforced.

[TBD: new system]