Maybe we should have not deprecated the ajax interface.

Brainstorming:

Add a method, something like "isInternalApi", to ApiBase that by default returns false.

Add a boolean "includeinternal" parameter to ApiHelp, which when specified would include these internal API modules.

Adjust ApiBase::makeHelpMsg() to take a boolean indicating whether internal API modules should be shown (i.e. whether "includeinternal" was given to action=help).

Then ApiHelp::execute(), if not passed a "modules" parameter explicitly, would check the flag and isInternalApi() to decide whether to include each module in the output. Modules like ApiQuery that have submodules would use the new parameter to their ::makeHelpMsg() methods to do the same.

The help output should also include indication of whether a module is internal, much like it now does for stuff like "This module only accepts POST requests".

I'm not sure whether we should also try to adjust the output of getAllowedParams() to omit these internal modules from the valid values for "action", or if that would be too expensive for too little gain (if we did do that, we'd need to do like how ApiPageSet handles generators). We certainly should be sure not to omit the internal modules for action=paraminfo though.

(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.

(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.

Change 158546 had a related patch set uploaded by Alex Monk:
Make it possible for API modules to hide their documentation behind an 'includeinternal' parameter

https://gerrit.wikimedia.org/r/158546

Change 160798 had a related patch set uploaded by Anomie:
API: HTMLize and internationalize the help, add Special:ApiHelp

https://gerrit.wikimedia.org/r/160798

Change 158546 abandoned by Legoktm:
API: Implement concept of 'internal' API modules

Reason:
Superseded by Ib14c00df06d85c2f6364d83b2b10ce34c7f513cc

https://gerrit.wikimedia.org/r/158546

Taken over by Brad.

Change 160798 merged by jenkins-bot:
API: HTMLize and internationalize the help, add Special:ApiHelp

https://gerrit.wikimedia.org/r/160798

Change 1010987 had a related patch set uploaded (by Jforrester; author: Jforrester):

[mediawiki/core@master] api: Tweak the 'internal' API label to explain that they shouldn't be used

https://gerrit.wikimedia.org/r/1010987

Change 1010987 merged by jenkins-bot:

[mediawiki/core@master] api: Tweak the 'internal' API label to explain that they shouldn't be used

https://gerrit.wikimedia.org/r/1010987