The REST APIs are not intended for public use. All of them are internal and used by JS code that exists in CheckUser

We should probably just drop the link and update the message to say these are for internal use and no documentation exists for them. This message was added by another WMF team, tagging them here

@KineticPelagic @BPirkle for the above, please fix as appropriate

In T429091#12016333, @Dreamy_Jazz wrote:

The REST APIs are not intended for public use. All of them are internal and used by JS code that exists in CheckUser

We should probably just drop the link and update the message to say these are for internal use and no documentation exists for them. This message was added by another WMF team, tagging them here

@HCoplin-WMF , what do you think of the idea to drop the link off the spec? Including the link was specifically a requirement in T425736: Create CheckUser API Module for the REST APIs in the extension. Based on our current linter rules, the following would occur:

• When externalDocs has no url or an invalid url based on a regex pattern, there is a warning.
• When externalDocs is not present, there is an error.

@Dreamy_Jazz -- I would err on the side of including the link in the spec, perhaps with the exception of if you are actually planning to remove the extension documentation from MediaWiki. Removing the link has the potential to cause more confusion down the road without much benefit, in my opinion.

I feel this way because:

• The spec will already be suppressed in terms of discoverability. We are not going to make it visible in the REST Sandbox, so public users won't easily encounter it. It is also marked as internal, which sends a message that public users shouldn't use it even if they do encounter it. We will soon add additional indicators of the internal nature to the discovery list as well, so that message should come across clearly.
• The MediaWiki docs about the extension will (presumably) continue to exist. If a user were to encounter the spec and see that the paths exist, it's not a big jump to just search for "CheckUser" and find the MediaWiki docs about the extension anyway, so removing the link feels like a bit of unnecessary "security through obscurity" when the obscurity really isn't that obscure.
• The API has additional layers of security already, with more to come. So even if someone does encounter the docs, they aren't able to use the API without extended rights. Similarly, we will work together next year to make it even more restricted.
• The spec will likely still be helpful for internal staff, so removing content that could be helpful for the folks who should be using the spec seems a little excessive.

In T429091#12033489, @HCoplin-WMF wrote:

@Dreamy_Jazz -- I would err on the side of including the link in the spec, perhaps with the exception of if you are actually planning to remove the extension documentation from MediaWiki. Removing the link has the potential to cause more confusion down the road without much benefit, in my opinion.

The reason I ask for the removal is a volunteer translator says the link isn't useful because it does not link to docs about the REST API

If the URL is required in the rest-module-checkuser.v0-desc message, then I guess this task should be declined

The ExternalDocs is supposed to give more information about the capability in general. Based on @KBach 's guidance, the general thought is that APIs that come from an extension should link to the documentation about that extension. I think it's expected that the external docs would not necessarily include additional reference documentation about the API, because that should largely be covered by the spec itself.

However, I do see the point about the scope of this ticket being more concerned with the content of the referenced page barely mentioning the API and not explicitly calling out REST existing at all. It seems like making a small edit to make that information a little clearer would be sufficient in this case to cover both needs. @Dreamy_Jazz is that something your team would be comfortable updating to add a little bit of context? For example, even just being more explicit in the API section to say that both Action and REST APIs are available, but are disabled by default?

In T429091#12060341, @HCoplin-WMF wrote:

...
However, I do see the point about the scope of this ticket being more concerned with the content of the referenced page barely mentioning the API and not explicitly calling out REST existing at all. It seems like making a small edit to make that information a little clearer would be sufficient in this case to cover both needs. @Dreamy_Jazz is that something your team would be comfortable updating to add a little bit of context? For example, even just being more explicit in the API section to say that both Action and REST APIs are available, but are disabled by default?

We moved documentation for the APIs to https://www.mediawiki.org/wiki/Help:Extension:CheckUser#APIs as https://www.mediawiki.org/wiki/Extension:CheckUser was getting too long. I've updated that help page to say that the REST APIs are internal and unstable in https://www.mediawiki.org/w/index.php?title=Help:Extension:CheckUser&diff=prev&oldid=8465295

I'd recommend the message links that section in the help page

Cool beans. Linking to that section directly is fine by me! Thank you for the update and guidance. @KineticPelagic could you update the link accordingly?