Tracking ticket for tasks related to modularizing the REST API and improving change management and versioning.

API Modules: Rationale and Context

Currently, the REST API framework is designed to manage a flat list of endpoint routes.
Versioning is applied per the conventioned established in T232485, but there is no mechanism to ensure consistency between related endpoints.
All core endpoints are currently exposed under the v1 version prefix, while each extension uses a separate prefix, typically followed by v0 marking the API as unstable.

This approach is problematic in the context of T323786: REST framework: Add support for outputting an OpenAPI (swagger) spec . Since we only have a flat list of endpoints, we can only generate a single spec that cover all of them. But that spec will be different on each wiki, depending on what extensions are enabled, so it cannot be versioned in a way that would provide useful guarantees to clients. This prevents proper change management for API endpoints.

To provide stable specs with meaningful versioning, the REST API should support the notion of "modules" that group related endpoints together. Each module will produce a seperate spec with a meaningful version. The version in the spec will correspond to the version in the endpoint URL (though only the major version number will be used in the URL). Each extension would define a separate module (or multiple). The endpoints exposed by core can be grouped into modules as well, to decouple the evolution of unrelated groups of endpoints.

Each module would be defined by a speparate file declaring the routes supported by it. The format of these files could be made compatible with OpenAPI spec files.

Note that we may still offer a aggregated spec covering all endpoints for ease of exploration. That spec would however be considerd an unversioned snapshot, it would not provide any guarantees across wikis or over time.

In practice, this couple mean for example:

• The endpoints currently available under /v1/page/{title} and /v1/revision/{id} would move to /content.v1/page/{title} and /content.v1/revision/{id} respectively.
• We would generate an OpenAPI spec for all endpoints under /content.v1/, which would be using semantic versioning and provide guarantees across wikis and over time.

For more information, see https://docs.google.com/document/d/1cKaaAzhd6WQPqOrvT_Fg5TKt1AaIh_ADt6ocZUoi3IQ/edit