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.
The transform endpoints within the MediaWiki REST API represent a set of functionality owned by the Parsoid (Content Transform) team. It therefore makes sense to have that team be able to independently manage and version that set of functionality, independently from the rest of the MediaWiki APIs. Creating this module will also act as an introduction to the new patterns, so that we may more easily increment a consolidated version for vNext, which will combine Wikimedia and MediaWiki transform endpoints into a single canonical version.
Conditions of acceptance
- Transform API module is created
- See: https://www.mediawiki.org/wiki/API:REST_API/Extensions <-- //The process may be slightly different, since this is moving content out of MediaWiki Core instead of an extension; MediaWiki Interfaces can help with any updated instructions and/or related framework changes that need to be implemented.
- A high(er) quality spec is generated for Transform API:
- See: https://www.mediawiki.org/wiki/Documentation/API_documentation/Reference
- A high level module description is created, with a link to the Transform 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
- Transform API module is available in the REST Sandbox dropdown
- Transform endpoints are removed from the "flat" MediaWiki definition
Helpful documentation
Implementation details
This is the first time we are breaking a part of MediaWiki Core into a module. There may be some kinks to figure out because of that.