Page MenuHomePhabricator

Audit and fix API help pages missing or incorrect help urls
Closed, ResolvedPublic

Description

I noticed https://www.mediawiki.org/w/api.php?action=help&modules=compare wasn't displaying its help url, because it's not defined in the PHP code...

I suspect that this might not be the only one.

Ideally, all WMF production/MW release bundled API modules should have these documented, where the pages exist...

Where they don't exist, they do want creating at some point...

$json = json_decode( file_get_contents( 'https://www.mediawiki.org/w/api.php?action=paraminfo&format=json&modules=' . urlencode( '**' ) ), true );
foreach( $json['paraminfo']['modules'] as $m ) {
    if ( $m['helpurls'] === [] ) {
        echo "| `" . $m['path'] . "` | `" . $m['classname'] . "` |\n";
    }
}

Event Timeline

Change 940924 had a related patch set uploaded (by Reedy; author: Reedy):

[mediawiki/core@master] ApiComparePages: Add help url

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

Change 940925 had a related patch set uploaded (by Reedy; author: Reedy):

[mediawiki/extensions/LiquidThreads@master] ApiThreadAction: Correct Help URL

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

Reedy renamed this task from Audit and fix API help pages missing help urls to Audit and fix API help pages missing or incorrect help urls.Jul 25 2023, 12:32 PM
Reedy updated the task description. (Show Details)

Based on mw.org...

PathClass
abusefiltercheckmatchMediaWiki\Extension\AbuseFilter\Api\CheckMatch
abusefilterchecksyntaxMediaWiki\Extension\AbuseFilter\Api\CheckSyntax
abusefilterevalexpressionMediaWiki\Extension\AbuseFilter\Api\EvalExpression
abusefilterunblockautopromoteMediaWiki\Extension\AbuseFilter\Api\UnblockAutopromote
abuselogprivatedetailsMediaWiki\Extension\AbuseFilter\Api\AbuseLogPrivateDetails
aggregategroupsMediaWiki\Extension\Translate\MessageGroupProcessing\AggregateGroupsActionApi
antispoofMediaWiki\Extension\AntiSpoof\ApiAntiSpoof
categorytreeMediaWiki\Extension\CategoryTree\ApiCategoryTree
centralauthtokenMediaWiki\Extension\CentralAuth\Api\ApiCentralAuthToken
centralnoticecdncacheupdatebannerApiCentralNoticeCdnCacheUpdateBanner
centralnoticechoicedataApiCentralNoticeChoiceData
centralnoticequerycampaignApiCentralNoticeQueryCampaign
checktokenApiCheckToken
cirrus-config-dumpCirrusSearch\Api\ConfigDump
cirrus-mapping-dumpCirrusSearch\Api\MappingDump
cirrus-profiles-dumpCirrusSearch\Api\ProfilesDump
cirrus-settings-dumpCirrusSearch\Api\SettingsDump
collectionMediaWiki\Extension\Collection\Api\ApiCollection
collection+addarticleMediaWiki\Extension\Collection\Api\ApiAddArticle
collection+addcategoryMediaWiki\Extension\Collection\Api\ApiAddCategory
collection+addchapterMediaWiki\Extension\Collection\Api\ApiAddChapter
collection+clearcollectionMediaWiki\Extension\Collection\Api\ApiClearCollection
collection+getbookcreatorboxcontentMediaWiki\Extension\Collection\Api\ApiGetBookCreatorBoxContent
collection+getcollectionMediaWiki\Extension\Collection\Api\ApiGetCollection
collection+getpopupdataMediaWiki\Extension\Collection\Api\ApiGetPopupData
collection+postcollectionMediaWiki\Extension\Collection\Api\ApiPostCollection
collection+removearticleMediaWiki\Extension\Collection\Api\ApiRemoveArticle
collection+removeitemMediaWiki\Extension\Collection\Api\ApiRemoveItem
collection+renamechapterMediaWiki\Extension\Collection\Api\ApiRenameChapter
collection+setsortingMediaWiki\Extension\Collection\Api\ApiSetSorting
collection+settitlesMediaWiki\Extension\Collection\Api\ApiSetTitles
collection+sortitemsMediaWiki\Extension\Collection\Api\ApiSortItems
collection+suggestarticleactionMediaWiki\Extension\Collection\Api\ApiSuggestArticleAction
collection+suggestundoarticleactionMediaWiki\Extension\Collection\Api\ApiSuggestUndoArticleAction
compareApiComparePages
createlocalaccountMediaWiki\Extension\CentralAuth\Api\ApiCreateLocalAccount
cspreportApiCSPReport
deleteglobalaccountMediaWiki\Extension\CentralAuth\Api\ApiDeleteGlobalAccount
discussiontoolscompareMediaWiki\Extension\DiscussionTools\ApiDiscussionToolsCompare
discussiontoolseditMediaWiki\Extension\DiscussionTools\ApiDiscussionToolsEdit
discussiontoolsfindcommentMediaWiki\Extension\DiscussionTools\ApiDiscussionToolsFindComment
discussiontoolsgetsubscriptionsMediaWiki\Extension\DiscussionTools\ApiDiscussionToolsGetSubscriptions
discussiontoolspageinfoMediaWiki\Extension\DiscussionTools\ApiDiscussionToolsPageInfo
discussiontoolspreviewMediaWiki\Extension\DiscussionTools\ApiDiscussionToolsPreview
discussiontoolssubscribeMediaWiki\Extension\DiscussionTools\ApiDiscussionToolsSubscribe
echomuteMediaWiki\Extension\Notifications\Api\ApiEchoMute
fancycaptchareloadMediaWiki\Extension\ConfirmEdit\FancyCaptcha\ApiFancyCaptchaReload
featuredfeedMediaWiki\Extension\FeaturedFeeds\ApiFeaturedFeeds
feedcontributionsApiFeedContributions
feedrecentchangesApiFeedRecentChanges
feedthreadsMediaWiki\Extension\LiquidThreads\Api\ApiFeedLQTThreads
filerevertApiFileRevert
flow-parsoid-utilsFlow\Api\ApiParsoidUtilsFlow
flowthankMediaWiki\Extension\Thanks\Api\ApiFlowThank
globalblockMediaWiki\Extension\GlobalBlocking\Api\ApiGlobalBlock
groupreviewMediaWiki\Extension\Translate\MessageGroupProcessing\GroupReviewActionApi
imagerotateApiDisabled
jsonconfigJsonConfig\JCApi
jsondataJsonConfig\JCDataApi
languagesearchUniversalLanguageSelector\Api\ApiLanguageSearch
managegroupsynchronizationcacheMediaWiki\Extension\Translate\Synchronization\ManageGroupSynchronizationCacheActionApi
managemessagegroupsMediaWiki\Extension\Translate\MessageGroupProcessing\ManageMessageGroupsActionApi
newslettersubscribeMediaWiki\Extension\Newsletter\Api\ApiNewsletterSubscribe
oathvalidateMediaWiki\Extension\OATHAuth\Api\Module\ApiOATHValidate
query+abusefiltersMediaWiki\Extension\AbuseFilter\Api\QueryAbuseFilters
query+abuselogMediaWiki\Extension\AbuseFilter\Api\QueryAbuseLog
query+babelMediaWiki\Babel\ApiQueryBabel
query+centralnoticeactivecampaignsApiCentralNoticeQueryActiveCampaigns
query+centralnoticelogsApiCentralNoticeLogs
query+cirrusbuilddocCirrusSearch\Api\QueryBuildDocument
query+cirruscompsuggestbuilddocCirrusSearch\Api\QueryCompSuggestBuildDoc
query+cirrusdocCirrusSearch\Api\QueryCirrusDoc
query+descriptionWikibase\Client\Api\Description
query+extdistbranchesMediaWiki\Extension\ExtensionDistributor\Api\ApiListExtDistBranches
query+extdistreposMediaWiki\Extension\ExtensionDistributor\Api\ApiListExtDistRepos
query+gadgetcategoriesMediaWiki\Extension\Gadgets\Api\ApiQueryGadgetCategories
query+gadgetsMediaWiki\Extension\Gadgets\Api\ApiQueryGadgets
query+globalallusersMediaWiki\Extension\CentralAuth\Api\ApiQueryGlobalAllUsers
query+globalblocksMediaWiki\Extension\GlobalBlocking\Api\ApiQueryGlobalBlocks
query+globalgroupsMediaWiki\Extension\CentralAuth\Api\ApiQueryGlobalGroups
query+globalrenamestatusMediaWiki\Extension\CentralAuth\Api\ApiQueryGlobalRenameStatus
query+globalusageMediaWiki\Extension\GlobalUsage\ApiQueryGlobalUsage
query+globaluserinfoMediaWiki\Extension\CentralAuth\Api\ApiQueryGlobalUserInfo
query+languageinfoApiQueryLanguageinfo
query+languagestatsMediaWiki\Extension\Translate\Statistics\QueryLanguageStatsActionApi
query+linterrorsMediaWiki\Linter\ApiQueryLintErrors
query+linterstatsMediaWiki\Linter\ApiQueryLinterStats
query+managemessagegroupsMediaWiki\Extension\Translate\MessageGroupProcessing\QueryManageMessageGroupsActionApi
query+mapdataKartographer\Api\ApiQueryMapData
query+messagecollectionMediaWiki\Extension\Translate\MessageLoading\QueryMessageCollectionActionApi
query+messagegroupsMediaWiki\Extension\Translate\MessageGroupProcessing\QueryMessageGroupsActionApi
query+messagegroupstatsMediaWiki\Extension\Translate\Statistics\QueryMessageGroupStatsActionApi
query+messagetranslationsMediaWiki\Extension\Translate\MessageLoading\QueryMessageTranslationsActionApi
query+mmcontentMediaWiki\MassMessage\Api\ApiQueryMMContent
query+oathMediaWiki\Extension\OATHAuth\Api\Module\ApiQueryOATH
query+pagetermsWikibase\Client\Api\PageTerms
query+threadsMediaWiki\Extension\LiquidThreads\Api\ApiQueryLQTThreads
query+transcodestatusMediaWiki\TimedMediaHandler\ApiTranscodeStatus
query+wikibaseWikibase\Client\Api\ApiClientInfo
query+wikisetsMediaWiki\Extension\CentralAuth\Api\ApiQueryWikiSets
rsdApiRsd
sanitize-mapdataKartographer\Api\ApiSanitizeMapData
scribunto-consoleMediaWiki\Extension\Scribunto\ApiScribuntoConsole
searchtranslationsMediaWiki\Extension\Translate\TtmServer\SearchTranslationsActionApi
securepollauthMediaWiki\Extension\SecurePoll\Api\ApiSecurePollAuth
setglobalaccountstatusMediaWiki\Extension\CentralAuth\Api\ApiSetGlobalAccountStatus
shortenurlMediaWiki\Extension\UrlShortener\ApiShortenUrl
sitematrixMediaWiki\Extension\SiteMatrix\ApiSiteMatrix
stasheditApiStashEdit
strikevoteMediaWiki\Extension\SecurePoll\Api\ApiStrikeVote
titleblacklistMediaWiki\Extension\TitleBlacklist\Api\ApiTitleBlacklist
torblockMediaWiki\Extension\TorBlock\ApiTorBlock
transcoderesetMediaWiki\TimedMediaHandler\ApiTranscodeReset
translationaidsMediaWiki\Extension\Translate\TranslatorInterface\Aid\TranslationAidsActionApi
translationcheckMediaWiki\Extension\Translate\Validation\CheckTranslationActionApi
translationentitysearchMediaWiki\Extension\Translate\TranslatorInterface\TranslationEntitySearchActionApi
translationreviewMediaWiki\Extension\Translate\TranslatorInterface\ReviewTranslationActionApi
translationstatsMediaWiki\Extension\Translate\Statistics\QueryTranslationStatsActionApi
ttmserverMediaWiki\Extension\Translate\TtmServer\TtmServerActionApi
ulslocalizationUniversalLanguageSelector\Api\ApiULSLocalization
ulssetlangUniversalLanguageSelector\Api\ApiULSSetLanguage
visualeditorMediaWiki\Extension\VisualEditor\ApiVisualEditor
visualeditoreditMediaWiki\Extension\VisualEditor\ApiVisualEditorEdit
webapp-manifestMobileFrontend\Api\ApiWebappManifest
webauthnMediaWiki\Extension\WebAuthn\Api\WebAuthn
wikiloveMediaWiki\Extension\WikiLove\ApiWikiLove
wikimediaeventsblockededitWikimediaEvents\ApiWikimediaEventsBlockedEdit

Change 940924 merged by jenkins-bot:

[mediawiki/core@master] ApiComparePages: Add help url

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

Change 941495 had a related patch set uploaded (by Reedy; author: Reedy):

[mediawiki/core@REL1_40] ApiComparePages: Add help url

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

Change 941496 had a related patch set uploaded (by Reedy; author: Reedy):

[mediawiki/core@REL1_39] ApiComparePages: Add help url

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

Change 941497 had a related patch set uploaded (by Reedy; author: Reedy):

[mediawiki/core@REL1_35] ApiComparePages: Add help url

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

Change 941496 merged by jenkins-bot:

[mediawiki/core@REL1_39] ApiComparePages: Add help url

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

Change 941495 merged by jenkins-bot:

[mediawiki/core@REL1_40] ApiComparePages: Add help url

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

Change 940925 merged by jenkins-bot:

[mediawiki/extensions/LiquidThreads@master] ApiThreadAction: Correct Help URL

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

Change 941497 merged by jenkins-bot:

[mediawiki/core@REL1_35] ApiComparePages: Add help url

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

Krinkle subscribed.

If I understand correctly, this task is asking each API module to ensure it includes a link to its help documentation. For example, at https://www.mediawiki.org/w/api.php?action=help&modules=compare there is a link to https://www.mediawiki.org/wiki/API:Compare.

A complete list of API modules that are missing documentation is in Reedy's previous comment: T342632#9041135.

The list includes many API modules in MediaWiki core, hence MediaWiki-Action-API is tagged. I'll add API Platform team to reflect this, since they don't have a Herald rule yet.

The list of API modules lacking docs also includes many extensions. Hopefully those will find their respective teams.

One of the extensions is CentralAuth, hence MediaWiki-Platform-Team was tagged, as a TODO item to fix the documentation for centralauthtoken at https://www.mediawiki.org/w/api.php?action=help&modules=centralauthtoken.

One of the extensions is CentralAuth, hence MediaWiki-Platform-Team was tagged, as a TODO item to fix the documentation for centralauthtoken at https://www.mediawiki.org/w/api.php?action=help&modules=centralauthtoken.

CentralAuth has a bunch of API endpoints, not just centralauthtoken.

Although it might be easier for a single person/team (presumably the API team?) to go through all these than to have a dozen teams project-manage and understand what's being asked from them.

API Platform will take this on and any thing that we come across that doesn't sit in our domain, we will consult with the owning team to get the work completed.

Change 965588 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[mediawiki/core@master] api: add missing help URLs that exist on mw.org

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

Change 965588 merged by jenkins-bot:

[mediawiki/core@master] api: add missing help URLs that exist on mw.org

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

Change 965801 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[mediawiki/extensions/UniversalLanguageSelector@master] Add API help URL to ApiLanguageSearch

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

Change 965802 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[mediawiki/extensions/SiteMatrix@master] Add API help URL to APISiteMatrix

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

Change 965803 had a related patch set uploaded (by Aaron Schulz; author: Aaron Schulz):

[mediawiki/core@master] api: remove invalid help url from AcquireTempUserName

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

If I change the script I can filter down to cases where mw.org pages actually exist to be linked to, it narrows down the entries quite a bit. One thing I ran into is inconsistent casing conventions. A few API: pages use camelcase where as other are lowercase (except the first char). Sometimes there is a redirect page from one casing to another. I'm assuming that lowercase version of the API: pages actually exist (at least as a redirect).

Adding in cases of mw.org enabled extensions where there is a link but there is no mw.org page adds just a few entries. Based on that, I made some more link patches to cover the remaining cases.

Missing API help URLS:
| `checktoken` | `ApiCheckToken` |
| `feedcontributions` | `ApiFeedContributions` |
| `feedrecentchanges` | `ApiFeedRecentChanges` |
| `filerevert` | `ApiFileRevert` |
| `imagerotate` | `ApiDisabled` |
| `languagesearch` | `UniversalLanguageSelector\Api\ApiLanguageSearch` |
| `rsd` | `ApiRsd` |
| `sitematrix` | `MediaWiki\Extension\SiteMatrix\ApiSiteMatrix` |
| `stashedit` | `ApiStashEdit` |
Invalid API help URLS:
| `acquiretempusername` | `ApiAcquireTempUserName` |
<?php
$json = json_decode( file_get_contents( 'https://www.mediawiki.org/w/api.php?action=paraminfo&format=json&modules=' . urlencode( '**' ) ), true );
$bogus = [];
$missing = [];
foreach( $json['paraminfo']['modules'] as $m ) {
    foreach ( $m['helpurls'] as $url ) {
        $urlCheck = 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:' . ucfirst( $m['path'] );
        if ( strcasecmp( $url, $urlCheck ) === 0 ) {
            $dbKey = substr( $url, strrpos( $url, ':' ) + 1 );
            $info = json_decode( file_get_contents( 'https://www.mediawiki.org/w/api.php?action=query&prop=info&titles=API:' . $dbKey . '&format=json' ), true );
            if ( isset( $info['query']['pages'][-1] ) ) {
                $bogus[] = "| `" . $m['path'] . "` | `" . $m['classname'] . "` |";
            }
        }
    }
    if ( $m['helpurls'] === [] ) {
        $info = json_decode( file_get_contents( 'https://www.mediawiki.org/w/api.php?action=query&prop=info&titles=API:' . ucfirst( $m['path'] ) . '&format=json' ), true );
        if ( !isset( $info['query']['pages'][-1] ) ) {
            $missing[] = "| `" . $m['path'] . "` | `" . $m['classname'] . "` |";
        }
    }
}

echo "Missing API help URLS:\n";
foreach ( $missing as $l ) {
    echo $l . "\n";
}

echo "Invalid API help URLS:\n";
foreach ( $bogus as $l ) {
    echo $l . "\n";
}

Using some grep wrappers I don't see any broken links from extensions that are not enabled on any WMF sites.

Change 965803 merged by jenkins-bot:

[mediawiki/core@master] api: remove invalid help url from AcquireTempUserName

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

Change 965801 merged by jenkins-bot:

[mediawiki/extensions/UniversalLanguageSelector@master] Add API help URL to ApiLanguageSearch

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

Change 965802 merged by Aaron Schulz:

[mediawiki/extensions/SiteMatrix@master] Add API help URL to APISiteMatrix

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