Description
The MediaWiki Interfaces team recently introduced a new pattern for defining self-contained REST API Modules within the MediaWiki REST framework for REST APIs. REST API modules represent collections of related endpoints, which can be independently managed from other REST API modules. They create controlled flexibility through federated ownership, while also ensuring that related capabilities are self-contained, can be independently versioned, and can share object definitions and the like. They are therefore particularly well-suited for extension REST API definitions, which are already self contained. Module adoption also allows for things like controlling how and where the API is published, in terms of the spec discovery endpoint and the REST Sandbox.
The OAuth REST API endpoints are well-suited to become an API Module, particularly as we look to make improvements to OAuth flows and may need to introduce new versions. Having a dedicated module will likely also help with discoverability of these endpoints, so that it is easier for developers to request and manage their tokens.
Conditions of acceptance
- OAuth API module is created
- A high(er) quality spec is generated for OAuth API:
- See: https://www.mediawiki.org/wiki/Documentation/API_documentation/Reference
- A high level module description is created, with a link to the OAuth extension documentation.
- Endpoints all have short descriptions and summaries
- Parameter descriptions are helpful to human readers
- Schemas are defined, with useful descriptions for all properties
- Examples are created where needed
- OAuth API module is available in the REST Sandbox dropdown
- OAuth endpoints are removed from the "flat" MediaWiki definition
Helpful documentation
Implementation notes
- The process for creating a module is fairly straightforward; we expect the hardest part to be coming up with appropriate descriptions within the schema and endpoint definitions. Based on other teams completing this work, the whole process to takes a day or two. MediaWiki Interfaces is also down to help as much as necessary!