There are too many different variants of the Parsoid API url scheme:
* Parsoid's "v1" API.
* Parsoid's "v2" API.
* RESTbase's API, which is a hybrid of Parsoid's v1 and v2 API with some unique features of its own (ie POST parameters named "wikitext" and "bodyOnly" instead of "wt" and "body").
* The API exposed by the ParsoidVirtualRESTService in mediawiki core, which claims to be a mirror of Parsoid's "v1" API, but in fact contains features of the RESTbase API (ie, the `/transform/X/to/Y/` route, and the use of a POST parameter named "wikitext").
The latter API is the one used by the Visual Editor code base, and mediawiki-core contains code to munge it into both Parsoid's *actual* v1 API and the RESTbase API.
In this task I plan to (a) update ParsoidVirtualRESTService to always issue v2 API requests, then (b) update VisualEditor to use the Parsoid v2 API instead of it's crazy hybrid. We can then (c) remove "v1" API support from Parsoid.
This will take us from 4 similar-but-crazily-different APIs to only two: Parsoid v2 and RESTbase.
In task T100680 I propose to introduce a new Parsoid v3 API which is substantially similar to the RESTbase API, after which we can deprecate and remove Parsoid's v2 API and we'll be down to a single API url scheme.
This will remove a bunch of hairy URL translation code from Parsoid, RESTbase, and mediawiki-core, as well as concentrating our efforts on a single API to document.