API Portal/Retrospective

This retrospective was written in June 2025 by User:APaskulin_(WMF) to discuss the lessons learned from the API Portal for the purpose of informing API documentation work in fiscal year 2025-2026.

Historical summary

The API Portal was created by the Wikimedia Foundation Platform Engineering Team in 2020 as part of the Platform Evolution program. It was ready to be announced and officially launched in February 2021, but the announcement was blocked by new management in order to first develop a more cohesive API strategy. In 2023, a new information architecture was designed and implemented in response to scope changes from Product management. From 2021 to 2025, the API Portal has remained live and used by a small audience, but it has never been officially announced by the Foundation.

Objectives

The original objectives of the API Portal were to:

• Create a single site that would:
  • provide documentation for API endpoints served through a unified routing scheme provided by the API Gateway
  • allow for creating and managing Wikimedia OAuth 2.0 clients
• Use a visual design that resembles popular API documentation sites, based on the Wikimedia design style guide
• Minimize cognitive overhead by reducing reliance on information stored in other wikis

Lessons learned: Documentation

Offer different pathways to discover information

The current iteration of the API Portal serves both API users and API maintainers. The information architecture accomplishes this by providing two main pathways to discover information:

• The Learn pathway offers task-focused code samples, tutorials, and topics to help users understand the Wikimedia ecosystem and get started with the right endpoints for their use case. This path hides the complexity of the different APIs available and the boundaries between them. Learn pages link to relevant reference docs in the API Catalog section for users to learn more about the endpoints and see what else is available.
• The API Catalog path intentionally exposes the complexity that the Learn path hides. It lists each API separately with an API homepage and reference docs. This allows us to expose the fact that different APIs have different policies, such as different rate limits. API homepages link to relevant pages within the Learn section. While I originally designed this pathway with API maintainers in mind, I now think that this pathway could also serve API users who want to see and navigate this complexity for themselves.

Since the Wikimedia API ecosystem is split between many different services, this strategy is worth reusing in future API documentation projects to effectively serve different types of users.

Avoid duplicating docs

The documentation in the API Portal is written in wikitext. Approximately 50% of the documentation in the API Portal is manually duplicated from other sources of documentation. This has resulted in documentation that is prone to becoming outdated. Future documentation projects should consider ways to use automation to reduce duplication and provide programmatic ways to guarantee the accuracy of the docs.

High maintenance cost of custom skin and extension

The API Portal wiki is part of the API Gateway system. This system includes three MediaWiki extensions, one MediaWiki skin, an Envoy cluster, a RateLimit service, and the API Portal wiki instance itself. The complexity of this system has resulted in high maintenance costs and difficulty in detecting feature regression. In particular, the WikimediaApiPortal skin and the WikimediaApiPortalOAuth extension carry high amounts of technical debt and lack clear maintainers and investment from the Foundation.

Tradeoffs of using a wiki as a documentation platform

The API Portal is a MediaWiki instance separate from existing documentation wikis like mediawiki.org. There are advantages and disadvantages to using a wiki as a documentation platform for this use case.

Advantages

• Ease of editing: Wikis offer the lowest barrier to entry for contributing to documentation. Even with restrictions in place on who can edit, editing the docs on wiki is the simplest path to contributing to the docs.
• Translation: Although not currently enabled on the API Portal, the MediaWiki Translate extension could be installed to provide a convenient and familiar system to translate documentation.
• Community collaboration: Talk pages provide a convenient way for users to ask questions, report bugs, and propose changes to the docs. There have been several instances of this since the API Portal has gone live. As of June 2025, there are 13 volunteer contributors who have joined the documentation editors group, one of which has made their only Wikimedia contribution on the API Portal.
• Page watcher notifications: Each API homepage includes a changelog for that API. By watching the page, users can receive notifications of changes to the API. This allows users to subscribe to only the updates that are relevant to them, as opposed to subscribing to a mailing list that shares updates for all APIs.

Disadvantages

• Administration: Each new wiki requires a community of administrators, page watchers, and other functionaries. Although participation in the API Portal wiki may interest some contributors to other documentation wikis, a new wiki requires building a new community from scratch; there is no existing community like the one that exists on mediawiki.org. There’s another risk here that adding another documentation wiki splits the community of interested contributors and weakens similar communities.
• Complexity: MediaWiki is a complex ecosystem. Bugs in the API Portal require troubleshooting to determine whether they originate from one of many extensions, skins, or from MediaWiki Core. In addition, bugs can arise from the interaction between the API Portal and the system of Wikimedia wikis.

Lessons learned: Developer experience

These lessons fall outside the scope of documentation and the API Portal, meaning that these issues cannot be fixed with documentation. They relate to the product decisions behind the API Gateway system as a whole. I’ve included them here because they have a major impact on the developer experience of the API Portal.

Note that these lessons apply only to APIs served through api.wikimedia.org, not to all APIs documented on the API Portal.

Complexity of OAuth as a system for API keys

The API Portal uses the MediaWiki OAuth extension as a system to identify apps based on API keys. However, OAuth is designed to enable a "Log in with Wikimedia" workflow in which users log in to an app with their Wikimedia account and take actions using their Wikimedia identity. This means that the API Portal uses OAuth outside of its intended use case, which results in a much more complicated system than a simple system of API keys, both for the developer experience, the documentation, and our ability to test and maintain the system. For example, one of the main users of the system was meant to be the WMF mobile apps, but after implementing the system, a member of the Mobile team asked on Phabricator if it was possible to use the system without OAuth.

For example, here are a few points of friction in the developer experience related to OAuth. For more details, see the user journey maps.

• If a Wikipedia mobile app wants to use a Wikimedia API through the API Portal, the OAuth spec requires that the app require users to log in with their Wikimedia account before they can even read content. This is required by the OAuth spec for security reasons.
• A traditional web app can provide read-only anonymous access, but is required to refresh its access token every four hours. (Disclaimer: The expiry period may have changed since I looked into this last.)
• Developers creating OAuth keys must have their keys manually approved by a group of people.
• Developers are subject to different rate limits depending on the type of OAuth flows their app uses.
• Developers are required to provide a User-Agent header in addition to using an OAuth workflow.

Complexity of project and language routing

The API Gateway allows developers to specify the project they want to query using path parameters. Because there are separate path parameters for project and language, the language parameter must be omitted for multilingual projects such as Commons. For example: https://api.wikimedia.org/core/v1/wikipedia/en/page/Main_Page versus https://api.wikimedia.org/core/v1/commons/page/Main_Page. This creates additional complexity which needs to be handled in the docs.

Community feedback

Feedback about the API Portal has been mixed.

Positive:

• I have received a few emails from community members with positive feedback such as "great job so far".
• The Lift Wing and Wikifunctions teams both chose to use the API Portal for their docs despite its experimental status because they thought it provided a better user experience than other available options.

Negative:

There has been resistance (both within WMF and within volunteer communities) to having a separate wiki for API docs.