⚓ T398348 API docs research and discovery

⚓ T398348 API docs research and discovery
Page Menu
Phabricator
Create Task
Maniphest
T398348
API docs research and discovery
Closed, Resolved
Public
Actions
Edit Task
Edit Related Tasks...
Create Subtask
Edit Parent Tasks
Edit Subtasks
Merge Duplicates In
Close As Duplicate
Edit Related Objects...
Edit Commits
Edit Mocks
Mute Notifications
Protect as security issue
Assigned To
KBach
Authored By
apaskulin
Jul 1 2025, 4:42 PM
2025-07-01 16:42:31 (UTC+0)
Tags
Tech-Docs-Team
(Done)
Referenced Files
None
Subscribers
Aklapper
apaskulin
HCoplin-WMF
KBach
TBurmeister
Description
As part of
WE5.2
"By the end of Q4, 70% of Wikimedia web API endpoints will be supported by common infrastructure", research options to present documentation for APIs using this common infrastructure.
This task description is a work in progress.
Assigned:
@TBurmeister
and
@KBach
Timeframe: Q1 fiscal year 2025-2026
Goals
Create recommendations, including options and tradeoffs, for presenting documentation for Wikimedia APIs using common infrastructure developed as part of WE5.2.
Outcomes
As part of work on this task, we have created the following artifacts:
API documentation strategy
, outlining goals and plans for Wikimedia API technical documentation
API documentation information architecture and content patterns
, describing minimum viable API documentation. This also includes a
style guide for a standard API changelog
Style guide for OpenAPI descriptions (OADs)
, with recommendations for language that should be used in OAD files that power OpenAPI explorers and other tooling
These artifacts will evolve over the coming months to accommodate requirements resulting from other API work.
We have also:
conducted research into features and technical architectures of popular API documentation sites, which informed some of our work on the artifacts listed earlier
supported the work on the standard API sandbox (
T400174
), including the process of deciding where the documentation and the sandbox should be hosted (
T400183
Work on API documentation continues in
T405569: API docs work - Q2 and Q3 2025/26
and its subtasks.
Original scope
APIs in scope for WE5.2
(restricted access)
Recommendations for the new API documentation experience
Style guide for reference documentation/OpenAPI definition descriptions
API changelog
API documentation standards and patterns
Other API documentation content: tutorials, code samples, concept overviews (instructions on how to create + examples)
...
Note: Not all of this work will complete in Q1; some work might be started in this task and later moved to a separate task or hypothesis.
Project plan
Research features and technical architecture of documentation websites for popular APIs
Participate in the process of selecting the location for the new documentation (
T400183
Clarify the available options and selection criteria
Identify benefits and trade-offs
Gather feedback
Make a recommendation
Decision made
Research best practices for API reference documentation and OpenAPI description
Investigate the limitations of the OpenAPI description (OAD) format itself
Catalog current API reference documentation patterns
MediaWiki REST API
Wikimedia REST (RESTBase) API
Liftwing
Wikibase REST API
Link Recommendation API
Wikimedia Analytics API
Wikimedia Enterprise API
Identify OAD content best practices
Write the OAD style guide
Share the style guide for review
Improve the style guide based on feedback
Identify and document standard API documentation patterns
API changelog
Documentation content strategy (content migrations, future content work, deprecations, etc.)
Resources
Decision brief
template
and
folder
(restricted access)
Related Objects
Search...
Task Graph
Mentions
Status
Subtype
Assigned
Task
Resolved
KBach
T398348
API docs research and discovery
Resolved
TBurmeister
T401711
Complete gap analysis of existing API documentation collections
Resolved
TBurmeister
T403864
Identify and document standard API documentation patterns
Mentioned In
T405571: Improve OAD style guide based on feedback and emerging requirements
T405569: API docs work - Q2 and Q3 2025/26
T401711: Complete gap analysis of existing API documentation collections
T399765: Design information architecture for cross-collection API docs navigation flows
Mentioned Here
T400174: [EPIC] WE5.2.1. Standardized API Sandbox presentation
T405569: API docs work - Q2 and Q3 2025/26
T405571: Improve OAD style guide based on feedback and emerging requirements
T405573: Improve API changelog style guide based on feedback and emerging requirements
T401711: Complete gap analysis of existing API documentation collections
T403864: Identify and document standard API documentation patterns
T399765: Design information architecture for cross-collection API docs navigation flows
T400183: WE5.2.1. Decide where to host API reference documentation and sandboxes
Event Timeline
apaskulin
created this task.
Jul 1 2025, 4:42 PM
2025-07-01 16:42:31 (UTC+0)
Restricted Application
added a subscriber:
Aklapper
View Herald Transcript
Jul 1 2025, 4:42 PM
2025-07-01 16:42:31 (UTC+0)
apaskulin
moved this task from
Backlog
to
Active projects
on the
Tech-Docs-Team
board.
Jul 1 2025, 4:42 PM
2025-07-01 16:42:45 (UTC+0)
apaskulin
updated the task description.
(Show Details)
Jul 1 2025, 6:52 PM
2025-07-01 18:52:52 (UTC+0)
KBach
changed the task status from
Open
to
In Progress
Jul 16 2025, 7:50 AM
2025-07-16 07:50:34 (UTC+0)
KBach
claimed this task.
KBach
triaged this task as
High
priority.
KBach
updated the task description.
(Show Details)
Jul 16 2025, 8:32 AM
2025-07-16 08:32:12 (UTC+0)
KBach
added a comment.
Jul 16 2025, 8:35 AM
2025-07-16 08:35:11 (UTC+0)
Comment Actions
Completed so far:
Initial research into API documentation features and technical architectures - results shared with the Technical Documentation Team
Identification of core deliverables, their requirements, priorities, and dependencies
KBach
updated the task description.
(Show Details)
Jul 16 2025, 8:37 AM
2025-07-16 08:37:12 (UTC+0)
TBurmeister
changed the status of subtask
T399765: Design information architecture for cross-collection API docs navigation flows
from
Open
to
In Progress
Jul 16 2025, 7:30 PM
2025-07-16 19:30:46 (UTC+0)
TBurmeister
added a subscriber:
HCoplin-WMF
Jul 16 2025, 7:38 PM
2025-07-16 19:38:53 (UTC+0)
Comment Actions
The
spreadsheet linked in the task description for APIs in scope
has a list of many APIs with lots of information about them; I don't see a clear list there of what is in/out of scope for this work -- it seems comprehensive. Am I missing something? Is there a list somewhere of which APIs are in scope?
@HCoplin-WMF
for input / visibility.
TBurmeister
added a comment.
Jul 17 2025, 3:31 PM
2025-07-17 15:31:05 (UTC+0)
Comment Actions
Ah, I have found this list in a notes doc. Is this accurate for which APIs are in scope?
MediaWiki Action API
MediaWiki REST API
RESTBase API/their successors on the REST Gateway
Liftwing API
Analytics APIs (AQS)
Wikidata REST API
HCoplin-WMF
added a comment.
Jul 22 2025, 7:28 PM
2025-07-22 19:28:58 (UTC+0)
Comment Actions
@TBurmeister
-- yup! That's a good list. For future reference, I'm tracking what APIs are considered in scope for common infrastrcuture on the
"API Counts" tab
, in Column G. If it's ticked off there, it's considered in scope. The only thing to note there is that the Wikidata APIs are currently being considered a bit of a "stretch" goal. :)
TBurmeister
added a comment.
Jul 24 2025, 2:47 PM
2025-07-24 14:47:38 (UTC+0)
Comment Actions
I see that Liftwing is not checked on the API Counts tab in the spreadsheet. So it is not in scope? Thus based on your previous comment, the list of what's in scope for now would be:
MediaWiki Action API - in scope for overall IA but not for new sandbox experience
MediaWiki REST API
Wikimedia REST (RESTBase) API
Analytics APIs (AQS)
Assumption: even if we are only designing an IA and improved experience for these 4 APIs right now, the IA we design must be extensible enough that it can accomodate future migration of existing endpoints from other APIs and/or new APIs. As we pursue more standardization (and perhaps modularization) of the infrastructure, more endpoints or API would be integrated into the increasingly unified navigation structure.
TBurmeister
mentioned this in
T399765: Design information architecture for cross-collection API docs navigation flows
Jul 24 2025, 2:50 PM
2025-07-24 14:50:39 (UTC+0)
HCoplin-WMF
added a comment.
Jul 24 2025, 2:55 PM
2025-07-24 14:55:28 (UTC+0)
Comment Actions
When calculating the baseline, we decided to consider Wikidata and the APIs that are currently routed through the API Portal to be "stretch" goals. It will be slightly more complicated to reroute them to common infrastructure, given everything the API Portal is currently responsible for.
For the sake of the documentation and information architecture, I would like to consider them as a stretch goal, as well. They will be a little bit trickier on that front -- unlike the other APIs in the list, these API largely outside of the scope of a given project or across projects. I think that's an important nuance in terms of how we frame interactions and what API options are available.
Said another way, I do think that Wikidata and Liftwing will break the patterns to a degree, so we should at least consider what they might look like. We also have more time to figure that out though -- optimistically we would be looking at ~Q3 or Q4 to even consider rerouting Liftwing.
KBach
added a comment.
Aug 1 2025, 9:44 AM
2025-08-01 09:44:47 (UTC+0)
Comment Actions
We are still selecting the location for the new documentation, currently in the process of filling out the
decision matrix
(restricted access) and discussing different benefits and trade-offs.
KBach
updated the task description.
(Show Details)
Aug 1 2025, 9:47 AM
2025-08-01 09:47:57 (UTC+0)
KBach
updated the task description.
(Show Details)
Aug 1 2025, 11:03 AM
2025-08-01 11:03:53 (UTC+0)
KBach
updated the task description.
(Show Details)
Aug 5 2025, 9:11 AM
2025-08-05 09:11:57 (UTC+0)
KBach
updated the task description.
(Show Details)
Aug 6 2025, 8:10 AM
2025-08-06 08:10:43 (UTC+0)
KBach
updated the task description.
(Show Details)
Aug 6 2025, 8:27 AM
2025-08-06 08:27:53 (UTC+0)
KBach
added a comment.
Aug 6 2025, 8:32 AM
2025-08-06 08:32:34 (UTC+0)
Comment Actions
We've made a recommendation for the location of the new API sandbox and documentation.
I am now focusing on OpenAPI description (OAD) constraints and best practices. This will help us formulate the OAD and reference documentation style guide, but can also directly support the API sandbox work.
KBach
updated the task description.
(Show Details)
Aug 13 2025, 7:27 AM
2025-08-13 07:27:31 (UTC+0)
KBach
updated the task description.
(Show Details)
Aug 14 2025, 10:25 AM
2025-08-14 10:25:27 (UTC+0)
KBach
added a comment.
Aug 14 2025, 10:28 AM
2025-08-14 10:28:50 (UTC+0)
Comment Actions
I'm cataloging current API reference documentation patterns for analysis (already done with MediaWiki REST API, moving on to RESTbase). I'm planning to start formulating style guide entries based on these patterns in the middle of next week.
KBach
updated the task description.
(Show Details)
Aug 21 2025, 12:02 PM
2025-08-21 12:02:17 (UTC+0)
KBach
added a comment.
Aug 21 2025, 12:05 PM
2025-08-21 12:05:50 (UTC+0)
Comment Actions
I have now finished constructing the API patterns catalog and am analyzing it as a basis for the OAD style guide. Wikimedia Analytics API and Wikimedia Enterprise API are not part of the catalog and will be used to evaluate the style guide recommendations.
KBach
added a comment.
Sep 4 2025, 9:16 AM
2025-09-04 09:16:08 (UTC+0)
Comment Actions
Work on the OAD style guide was delayed and is still continuing. Currently planning to have the first draft ready for review by end of next week (12 September).
TBurmeister
added a comment.
Sep 4 2025, 5:23 PM
2025-09-04 17:23:52 (UTC+0)
Comment Actions
I've started moving content around and creating the scaffolding for where we will provide all the API documentation standards / patterns at
. While there are currently many red links, much of this content does already exist elsewhere and just needs to be migrated into this more organized central location. In the coming week I will be doing that, along with creating new content as needed to adapt our
existing doc templates
to express more API-specific content guidance for API maintainers/doc publishers.
TBurmeister
updated the task description.
(Show Details)
Sep 4 2025, 5:24 PM
2025-09-04 17:24:50 (UTC+0)
TBurmeister
removed a subtask:
T399765: Design information architecture for cross-collection API docs navigation flows
TBurmeister
mentioned this in
T401711: Complete gap analysis of existing API documentation collections
Sep 4 2025, 5:28 PM
2025-09-04 17:28:28 (UTC+0)
TBurmeister
added a subtask:
T401711: Complete gap analysis of existing API documentation collections
TBurmeister
changed the status of subtask
T403864: Identify and document standard API documentation patterns
from
Open
to
In Progress
Sep 5 2025, 8:31 PM
2025-09-05 20:31:07 (UTC+0)
KBach
updated the task description.
(Show Details)
Sep 11 2025, 1:07 PM
2025-09-11 13:07:58 (UTC+0)
KBach
added a comment.
Sep 11 2025, 1:10 PM
2025-09-11 13:10:31 (UTC+0)
Comment Actions
First draft of the OAD style guide has been shared for review. I'll be improving the document based on feedback over the coming weeks. Now focusing on the API changelog and documentation content strategy.
TBurmeister
updated the task description.
(Show Details)
Sep 11 2025, 3:37 PM
2025-09-11 15:37:25 (UTC+0)
TBurmeister
added a comment.
Sep 11 2025, 3:42 PM
2025-09-11 15:42:02 (UTC+0)
Comment Actions
Recommendations for API doc collection structure and contents are now drafted and shared for review, see
T403864
. Once the content patterns are approved by stakeholders, the next step is to finalize
T401711
by completing a gap analysis that captures the work required to bring each of those API doc collections more into alignment with our recommendation for more standardized structure and content.
I have also shared a draft of an API documentation strategy to define future work. Specification of required content migrations can't be done until we have some alignment on future goals and timelines around the existing API portal.
KBach
added a comment.
Sep 18 2025, 12:12 PM
2025-09-18 12:12:18 (UTC+0)
Comment Actions
A proposal for the standard API changelog structure and format is now in review. Currently focusing on the API documentation content strategy and the plans for Q2.
KBach
mentioned this in
T405569: API docs work - Q2 and Q3 2025/26
Sep 25 2025, 11:11 AM
2025-09-25 11:11:21 (UTC+0)
KBach
mentioned this in
T405571: Improve OAD style guide based on feedback and emerging requirements
Sep 25 2025, 11:22 AM
2025-09-25 11:22:56 (UTC+0)
KBach
updated the task description.
(Show Details)
Sep 25 2025, 11:50 AM
2025-09-25 11:50:17 (UTC+0)
KBach
added a comment.
Sep 25 2025, 12:15 PM
2025-09-25 12:15:23 (UTC+0)
Comment Actions
First drafts of the
OAD style guide
and the
API changelog style guide
are now published on mediawiki.org. Work on these documents will continue in
T405571: Improve OAD style guide based on feedback and emerging requirements
and
T405573: Improve API changelog style guide based on feedback and emerging requirements
respectively.
We're still finalizing documentation content strategy, focusing primarily on work planned for Q2 and collected in
T405569
KBach
updated the task description.
(Show Details)
Sep 25 2025, 12:15 PM
2025-09-25 12:15:51 (UTC+0)
KBach
updated the task description.
(Show Details)
TBurmeister
updated the task description.
(Show Details)
Sep 25 2025, 4:21 PM
2025-09-25 16:21:51 (UTC+0)
Comment Actions
Content strategy is now published on-wiki at
TBurmeister
closed subtask
T403864: Identify and document standard API documentation patterns
as
Resolved
Sep 25 2025, 4:25 PM
2025-09-25 16:25:39 (UTC+0)
KBach
closed this task as
Resolved
Sep 26 2025, 9:34 AM
2025-09-26 09:34:43 (UTC+0)
KBach
updated the task description.
(Show Details)
KBach
added a comment.
Edited
Sep 26 2025, 9:38 AM
2025-09-26 09:38:32 (UTC+0)
Comment Actions
All work planned for this task is now complete and summarized in task description, in the Outcomes section. API documentation work continues in
T405569
TBurmeister
moved this task from
Active projects
to
Done
on the
Tech-Docs-Team
board.
Sep 26 2025, 3:23 PM
2025-09-26 15:23:01 (UTC+0)
TBurmeister
closed subtask
T401711: Complete gap analysis of existing API documentation collections
as
Resolved
Mar 25 2026, 4:15 PM
2026-03-25 16:15:45 (UTC+0)
Log In to Comment
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct.
Wikimedia Foundation
Code of Conduct
Disclaimer
CC-BY-SA
GPL
Credits