Wikimedia Technical Documentation Team/API documentation strategy/Gaps - MediaWiki
Jump to content
From mediawiki.org

This page describes progress towards aligning documentation for Wikimedia APIs with the Wikimedia API documentation standards. Metrics for pages on mediawiki.org comes from the Technical Documentation Metrics Generator.

APIs aligned with documentation standards

[edit]
API Info architecture Content
Analytics API Yes Yes
MediaWiki REST API Yes Yes
Wikimedia REST API Yes Yes
Wikifeeds API Yes Yes
Wikifunctions API Yes Yes
Page Description API Yes Yes
Link Recommendation API Yes Yes
Lift Wing API Yes Yes

Coming soon: Tracking for reference docs standards

History

[edit]
Date Info architecture Content
10/2025 1/8 1/8
12/2025 2/8 2/8
3/2026 8/8 8/8

Standards

[edit]

To evaluate whether an API aligns with the documentation standards, we use these criteria.

Information architecture

[edit]

These criteria ensure the API docs are discoverable and navigable.

  1. The API is listed in the API catalog on the Wikimedia APIs landing page
  2. The API has a landing page on mediawiki.org titled "Example Name API"

Content

[edit]

These criteria ensure the API docs are usable and complete.

  1. The API landing page uses the standard format
  2. Any subpages of the API landing page are organized by content pattern
  3. All pages pass the Wikimedia Documentation Linter with zero warnings

Reference

[edit]

These criteria evaluate the API reference docs.

  1. API reference docs use an OpenAPI description
  2. [Work in progress] The OpenAPI description passes the Wikimedia OpenAPI Linter with zero errors

Analytics API

[edit]
Status
Yes Information architecture and content standardized
Landing page
wmdoc:analytics-api

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes Landing page available on doc.wikimedia.org as part of a standalone site
Landing page format Yes
Subpage organization Yes
Style lint Yes
Has OpenAPI Yes
OpenAPI lint N Linter is WIP

Metrics

[edit]
Baseline metrics
  • Number of pages: 22
  • % of pages marked as historical or obsolete: 0%
  • % of pages with translations: 0%
  • Key locations that link to the API landing page: doc.wikimedia.org
  • Primary sources of incoming traffic:
    • 74% from wikitech.wikimedia.org (data for 2024 July through 2025 September)

Most-viewed pages within the collection (data for 2024 July through 2025 September):

Page URL Pageviews Unique Pageviews Bounce Rate Avg. Time on Page Exit Rate
analytics-api 6,169 5,124 71% 00:00:44 66%
documentation 1,507 1,338 95% 00:00:36 74%
/index 1,632 1,293 43% 00:00:42 65%
reference 1,234 979 78% 00:01:01 68%
examples 962 858 91% 00:00:29 76%
concepts 621 481 57% 00:00:47 32%
tutorials 168 139 67% 00:01:28 44%
/changelog.html 22 17 100% 00:00:41 41%
/contributing.html 18 15 100% 00:01:27 27%

See also

[edit]

MediaWiki REST API

[edit]
Status
Yes Information architecture and content standardized
Landing page
API:REST API

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes
Landing page format Yes
Subpage organization Yes
Style lint Yes
Has OpenAPI Yes
OpenAPI lint N Linter is WIP

Metrics

[edit]
Baseline metrics
  • Average daily pageviews: 300
  • Percentage of pages with translate syntax: 25.00%
Succinct score Length in bytes Section to length ratio Developer relevance score Technical content score Links to code Code samples Popularity score Incoming links Visiting watcher percent More than 1 edit in past 6mo
API:REST API Great 9,008 500.4 Great 100 1 True 70 293 None Yes
API:REST API/Reference May need work 67,686 325.4 May need work 50 0 True 20 50 None No
API:REST/Extensions/Documentation Template Great 749 249.7 Needs improvement 50 0 True 0 1 None No
API:REST API/Status codes Great 1,952 488.0 May need work 50 0 True 20 29 None No
API:REST API/Conditional requests Great 2,112 704.0 May need work 50 0 True 20 29 None No
API:REST API/Extensions Great 7,840 1,120.0 Good 50 0 True 40 357 None No
Post-standardization metrics

Note: One-to-one comparison isn't possible for all pages, some pages were deprecated and two new pages were created. These tech docs metrics are still experimental; we're still testing their utility for real projects, and they may not accurately reflect tangible doc improvements.

Succinct score Length in bytes Section to length ratio Developer relevance score Technical content score Links to code Code samples Popularity score Incoming links Visiting watcher percent More than 1 edit in past 6mo
API:REST/Extensions Needs improvement 37 5.3 Needs improvement 0 0 False 0 1 None No
API:REST/Extensions/Documentation_Template Great 749 249.7 Needs improvement 50 0 True 0 2 None No
API:REST_API Great 4,315 863.0 Good 50 2 False 70 295 None Yes
API:REST_API/Extensions Great 7,894 1,127.7 Good 50 0 True 40 372 None No
API:REST_API/Reference May need work 67,699 327.0 May need work 50 0 True 30 53 None No
API:REST_API/Status_codes Great 1,952 488.0 May need work 50 0 True 20 31 None No
API:REST API/Get started Great 1,896 237.0 May need work 50 0 True 20 32 None No
API:REST API/Policies Great 1,739 248.4 Needs improvement 0 0 False 20 33 None No
API:REST_API/Changelog May need work 1,763 176.3 Needs improvement 0 0 False 20 47 None No

See also

[edit]

Wikimedia REST API

[edit]
Status
Yes Information architecture and content standardized
Landing page
Wikimedia REST API

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes
Landing page format Yes
Subpage organization N/A No subpages
Style lint Yes
Has OpenAPI Yes
OpenAPI lint N Linter is WIP

Metrics

[edit]
Baseline metrics
Succinct score Length in bytes Section to length ratio Developer relevance score Technical content score Links to code Code samples Popularity score Incoming links Visiting watcher percent More than 1 edit in past 6mo
Wikimedia_REST_API Great 3,721 744.2 Needs improvement 0 0 False 40 185 None No

See also

[edit]

Wikifeeds API

[edit]
Status
Yes Information architecture and content standardized
Landing page
Wikifeeds API

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes
Landing page format Yes
Subpage organization Yes
Style lint Yes
Has OpenAPI Yes
OpenAPI lint N Linter is WIP

Metrics

[edit]
  • API landing page on the API Portal had 255 average page views per month in 2025 (source)

See also

[edit]

Wikifunctions API

[edit]
Status
Yes Standardized
Landing page
Wikifunctions API

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes
Landing page format Yes
Subpage organization N/A No subpages
Style lint Yes
Has OpenAPI N/A This API is a set of Action API modules, so it cannot have an OAD
OpenAPI lint N/A

Metrics

[edit]
Baseline metrics

Standard doc metrics are unavailable because api.wikimedia.org is not supported by the Tech Docs Metrics Generator.

API Portal pageviews:

Page 30d views
Wikifunctions API 208
Wikifunctions API/Reference no data
Wikifunctions API/Reference/Run function 252
Wikifunctions API/Reference/Fetch object 176

See also

[edit]

Page Description API

[edit]
Status
Yes Information architecture and content standardized
Landing page
Page Description API

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes
Landing page format Yes
Subpage organization N/A No subpages
Style lint Yes
Has OpenAPI Yes
OpenAPI lint N Linter is WIP

Metrics

[edit]
  • API landing page on the API Portal had 162 average page views per month in 2025 (source)

See also

[edit]
[edit]
Status
Yes Information architecture and content standardized
Landing page
Link Recommendation API

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes
Landing page format Yes
Subpage organization N/A No subpages
Style lint Yes
Has OpenAPI Yes
OpenAPI lint N Linter is WIP

Metrics

[edit]
  • API landing page on the API Portal had 59 average page views per month in 2025 (source)

Lift Wing API

[edit]
Status
Yes Information architecture and content standardized
Landing page
wikitech:Machine Learning/LiftWing/API

Criteria

[edit]
Criteria Status Note
In API catalog Yes
Has landing page Yes Exception: This landing page is on Wikitech alongside existing documentation.
Landing page format Yes
Subpage organization Yes
Style lint Yes
Has OpenAPI N Planned work for April-June 2026
OpenAPI lint N

Metrics

[edit]
  • API landing page on the API Portal had 104 average page views per month in 2025 (source)

See also

[edit]

Out of scope

[edit]
  • Enterprise APIs
  • Action API
  • Wikidata APIs: Additional work and collaboration is required; this product is owned by WMDE. Need outreach and discussion prior to any attempt to standardize Wikidata docs to align with WMF-owned APIs.
  • MediaWiki Core REST API: Duplicate of the MediaWiki REST API; to be deprecated
Retrieved from "https://www.mediawiki.org/w/index.php?title=Wikimedia_Technical_Documentation_Team/API_documentation_strategy/Gaps&oldid=8317579"