(In reply to Brad Jorsch from comment #2)
> (In reply to James Forrester from comment #0)
> > For example, action=visualeditor is an internal API for the VisualEditor
> > client to talk to its server, isn't really useful for third parties, and
> > isn't remotely stable. However, because it's a built-in assumption that APIs
> > are for third-party use rather than every tool being the first client of its
> > API, this isn't possible. Boo.
> 
> Ideally a tool's API would be perfectly usable by third parties, not
> something overly specific to the one tool's internal implementation,
> although that may not always be possible. I don't know which is the case for
> VE's API or if it's just that it's not yet stable.

Completely agreed in the general case that we should encourage tools to create APIs that are useful for third parties. VE, as an exclusive consumer of APIs, comes up against the problem of the existing APIs in MW and extensions not actually providing the necessary features — we're well aware of how bad this is in some areas! My view is that all tools, core and otherwise, should be expected to be the first client of their own, normally public API rather than magically and silently reach into the codebase to make changes that other tools cannot (EditPage.php, I'm looking at you).

With VE's API, it's a combination of:

* not yet sufficiently stable (new features and formats being added each week or so),
* not a long-term prospect (this exists mostly to code around a lack of genericness in MW, and eventually we'll fix that rather than keep this), and
* not being a 'real' API (much of the content of the API is available from other API calls, but having a single call improves efficiency for VE's client).

As an illustrated example, see this change made this week to VE's API to add hinting to links that don't exist (so VE can add red colouring): https://gerrit.wikimedia.org/r/#/c/118045/14/ApiVisualEditor.php

This:
* changed just yesterday,
* is intended to be replaced reasonably soon with a proper Parsoid post-processor to sit in front of the HTML+RDFa cache for making changes that are currently parser cache-busting like this, and
* is trivially something that can be provided by the pre-existing public APIs.