Hypothesis owner: @apaskulin
Hypothesis owner delegate: @HCoplin-WMF
Start date: January 12, 2026
Target completion date: March 27, 2026
Actual completion date:
Hypothesis ID: WE5.2.11

Hypothesis

If we experiment and establish processes for standardizing documentation currently in the API Portal, we can consolidate sources of information and improve documentation consistency.

Scope

In scope:

• Documentation on api.wikimedia.org
• Documentation for APIs available through api.wikimedia.org

Project plan

• Communications and planning
  • Phase 1 communications (basic announcement)
    • Post to API Portal
      • Talk:Community
      • Talk:Contributing
      • Site banner
      • Notices on Community and Maintainers pages
    • wikitech:API Portal
    • WMF internal Slack
  • T415923: Plan shutdown process for the API Portal
  • Phase 2 communications (detailed plans; tech news, etc.)
• Content migration
  • Migrate docs for individual APIs
    • [Ready for redirect] T415803: Move Core API docs off the API Portal
    • [Ready for redirect] T415312: Move Link Recommendation API docs off the API Portal
    • [In progress] T415310: Move Wikifunctions API docs off the API Portal
    • [In progress] T415687: Move Feed API docs off the API Portal
    • [In progress] T415686: Move Page Description API docs off the API Portal
    • [Outreach/research] Lift Wing API
  • Migrate general API docs
    • Decide on information architecture (IA)
    • Projects and languages
    • Reusing free content
    • Stability policy
    • Best practices for bots and tools
    • [Needs links to docs] Use cases
    • API guidelines: Archived to Wikitech
    • Authentication guide
    • Security best practices
    • Rate limits
    • Conditional requests
• Content standardization (epic: T405969)
  • T406369: Lift Wing API documentation standardization
  • T406608: Wikifunctions API documentation standardization
  • T416019: Redirect mw:API:REST API/Reference to Special:RestSandbox
  • T416586: Review reference documentation moved off the API Portal

API Portal components

API Portal components:

• Wiki instance (API Portal content audit)
• Skin:WikimediaApiPortal (used only on the API Portal)
• Extension:WikimediaApiPortalOAuth duplicating functionality provided by Extension:OAuth (used only on the API Portal)
• Phabricator projects: API Portal, Wikimedia API Portal, MediaWiki-extensions-WikimediaApiPortalOAuth

Related components:

• API Gateway Envoy instance (to be deprecated; see T413438)

Background

In 2020, the Wikimedia Foundation Platform Engineering Team wanted to create a home for Wikimedia API docs that was similar to other popular API docs sites, and that allowed developers to more easily create and manage API keys.

Building the API Portal as a standalone wiki benefits from the advantages of MediaWiki:

• Ease of editing
• Ability to translate content
• Community collaboration through talk pages, watchlists, and other features

However, using a standalone wiki for the API Portal also has disadvantages:

• Administration: Each new wiki needs a community of administrators, page patrollers, and other functionaries. A new wiki adds work for the Wikimedia technical community.
• Technical complexity: MediaWiki is a complex ecosystem. Since the API Portal works differently from other Wikimedia wikis, we often find bugs that come from interactions with extensions, skins, and other wikis.
• Visual inconsistency: The API Portal’s simplified visual design makes it difficult to access wiki features like special pages. In addition, global skin preferences can override the API Portal’s visual design entirely, making the site difficult to use.

Wikimedia Foundation’s Product Management, MediaWiki Interfaces, and Tech Docs teams have decided that the disadvantages of implementing the API Portal as a standalone wiki outweigh the advantages. We’re still working on exact plans and schedules for shutting down the Portal, but here is a general idea of what to expect:

• Endpoints: api.wikimedia.org endpoints will continue to work as currently documented until at least June 2026. Starting in the second half of 2026, api.wikimedia.org endpoints will be migrated to new routes and eventually deprecated.
• API keys: Most API keys created through the API Portal will continue to work. You can manage your API keys through Special:OAuthConsumerRegistration on Meta-Wiki.
• Docs: Documentation from the API Portal will be consolidated and moved to other technical documentation wikis.

Information architecture

• mw:Wikimedia APIs – main landing page for Wikimedia APIs
• mw:Wikimedia APIs/subpages – topics that apply to multiple APIs
• mw:[API name] API – landing pages for an individual API
• mw:[API name] API/subpages – topics that apply to an individual API
• mw:[tutorial name] – API tutorials
• wikitech:API Portal/Deprecation – Information about deprecated api.wikimedia.org functionality. We can use this as an intermediary source of information to direct users to docs for API Portal APIs that are available elsewhere.

All APIs in the collection will have a landing page on mediawiki.org that uses this structure for consistency, but if those docs already exist on another wiki, the docs themselves can remain there instead of being migrated to mediawiki.org.

Resources

• https://techblog.wikimedia.org/2025/06/12/apis-as-a-product-investing-in-the-current-and-next-generation-of-technical-contributors/
• https://wikitech.wikimedia.org/wiki/API_Portal/Retrospective
• https://wikitech.wikimedia.org/wiki/Delete_a_wiki
  • “Usually, wikis are closed, not deleted.”
  • Example of a deleted wiki: https://meta.wikimedia.org/wiki/Sep11wiki
    • “It was made read-only in September 2006[1], and later deleted from Wikimedia entirely in early 2007, but remains available on the Wayback Machine, and backups of the database are still available on the Wikimedia dumps site and on the Internet Archive.”
• https://meta.wikimedia.org/wiki/Closing_projects_policy
• https://wikitech.wikimedia.org/wiki/Close_a_wiki
• https://meta.wikimedia.org/wiki/Proposals_for_closing_projects
  • “The [deleted] wiki should be redirected to another URL”
• https://meta.wikimedia.org/wiki/Closed_wiki
  • https://noc.wikimedia.org/conf/dblists/closed.dblist
  • Example of a closed wiki: https://transitionteam.wikimedia.org/wiki/Main_Page