MediaWiki Product Insights/Artifacts/KR 5.5: API Listening Tour Summary

Technical volunteers directly contribute to mission scale and trust by creating automated monitoring and moderation tools, facilitating bulk changes to keep articles organized, surfacing missing links and citations to raise the bar on quality, and creating unique stand alone applications that inspire readers to consume and interact with knowledge in new ways. Delivering the same level of delight back to our technical volunteer and developer community requires investment, attention, and collaboration.

Over the coming years, we plan to focus on transitioning to treat our APIs as products. The FY2526 key result WE5.2 focuses on enhancing our API experiences. The specific KR text reads:

By the end of Q4 2025, 70% of Wikimedia web API endpoints will be supported by common infrastructure that enables us to provide a more consistent developer experience, reduce developer burden, and improve approachability of Wikimedia web API experiences.

This work will be broken into a few key themes that reflect the pain points and opportunities captured through the listening tour. Additionally, we hope that this work will result in the following outcomes:

• Lessen the learning curve for new developers.
• Make developer experience consistent across APIs.
• Improve documentation accuracy and discoverability.
• Clarify endpoint intent, usage, and lifecycle expectations.
• Improve API platform sustainability.
• Deeply understand our users and usage patterns.

Below is a summary of the listening tour we recently completed, which motivated these outcomes. We hope that this is a first step in working together with the community to shape the future of Wikimedia APIs.

Introduction

The Wikimedia Foundation has not historically treated our web (HTTP) APIs as their own product offering. Instead, API authors were responsible for creating their own standards and, at times, even their own hosting and access infrastructure. While this allowed us to move quickly, that approach has become both unsustainable for us to maintain internally, and has come at the expense of consistency and ease of use for technical builders.

To better understand the existing gaps and pain points related to the Wikimedia API developer experience, the MediaWiki Interfaces team conducted an API listening tour as part of WE5.5 in FY2425. We see this as an opportunity to better understand and serve our technical contributors, so that we can guarantee the technical support required to support a multi-generational future for all of the Wikimedia communities.

Approach

We conducted interviews with developers within the foundation and across the community to gain more insights about the experience of using Wikimedia APIs. An initial open call for volunteer input attracted some long-time Wikimedians to tell us about their experiences, but we quickly realized that we were not creating a full picture. We were missing the voices of new technical contributors. Capturing these voices is critical – they directly represent the potential next generation of volunteers, as they have a fresh perspective on what it’s like to start using our APIs for the first time. To capture those voices, we began a more targeted reach-out, where we specifically requested feedback from new Foundation staff and technical volunteers who had been working with Wikimedia for less than 5 years.

While interviews were not run strictly off of a script, we shared sample questions to help participants understand what we were trying to learn and prepare some responses. Interview insights were also supplemented by the 2025 Developer Satisfaction Survey, where we added questions related to API experiences for the first time. Survey responses contextualized and predominately aligned with the interview results.

Personas

Through the conducted interviews, we identified a few key pathways for how people were joining the technical Wikimedia communities. We began by translating these commonalities into the personas listed below. We recognize that this list does not completely capture or exhaustively represent the journey for every Wikimedian; however, we find these personas helpful to simplify and structure some of the common developer journeys.

Wikimedian-first developers: These developers typically start as editors, moderators, and/or admins of their Wikimedia communities. They are deeply familiar with the workflows and challenges that they face, and would like to solve problems at scale. In some cases, these developers already know how to code from other training, but many are self-taught using Wikimedia solutions specifically.

Open source contributors: Developers in this category already know how to code, and want to use their skills to contribute to causes they are passionate about. This includes growing open source projects specifically, as well as the Wikimedia mission of making knowledge more freely available for everyone. However, many developers are unfamiliar with the inner workings of Wikimedia communities, including specific guidelines for editing or patrolling practices. They are looking for guidance on specific projects or opportunities to support the mission.

On-Wiki Script Author: Script authors wish to solve a specific, well understood problem, in support of their own workflows or specific wiki project community. This may be their first introduction to writing code, and they may not consider themselves developers. Typically, their first step will be copying an existing on-wiki user script, then editing it to suit their needs.

Vibe coder: Vibe coding allows developers to implement new ideas faster, particularly when working with an unfamiliar set of APIs, libraries, or programming languages. Instead of spending time trying to understand the documentation and syntax themselves, they rely on AI to create the scaffolding and basic functionality, then the developer can focus on debugging and expanding the feature set. This could be a particularly appealing approach when working as a volunteer with limited time and resources to contribute to a project. Vibe coding is becoming increasingly prevalent for both community developers and developers who wish to utilize Wikimedia data for external purposes.

Researchers: Researchers are interested in understanding metrics about Wikimedia, or how content has evolved within our ecosystem. In some cases, they are exclusively interested in metadata to investigate usage patterns; in others, they are interested in exploring changes to language, sentiment, or content coverage over time.

Content reusers: Factual content created by humans is highly valuable. Some common content reuse use cases include enabling AI/ML training, or embedding relevant content in external experiences, such as within search result summary boxes. Content reusers will typically start by pulling content in bulk to determine what is most useful. In some cases, this is a one time operation where they simply need a large data set for a specific training opportunity; in others, they are more interested in recent changes so that their external content may remain up to date. In all cases, the content is repackaged and used to add value to a system outside of Wikimedia.

Foundation feature-er: Software engineers employed by the Foundation are also heavy users of the Wikimedia APIs. They are building scalable, reusable features that serve millions of readers and contributors a day. Foundation staff is a mix of long time volunteers and people who are passionate about serving the mission but do not have a history of volunteering.

Learnings

By comparing notes across interviews and results from the developer survey, we noticed several recurring themes and commonalities. The listening tour surfaced many pain points and challenges that developers face when they are building a tool for the first time, maintaining existing tools, or are trying to engage with other developers, some of which are outlined below. This list is non-exhaustive, and instead highlights some of the key learnings, observations, and pain points. This listening tour also uncovered many positive experiences and anecdotes for the current offerings, which we aim to elevate and protect as we move forward.

Ongoing support for existing solutions

A clear need arose for improving clarity and support for our existing API solutions. Specifically, we do not wish to retire the existing solutions or universally treat them as legacy. We recognize the power, flexibility, and robust coverage of the Action API, and we see the value and creativity it enables. We also see great potential in expanding complementary coverage for more modern frameworks like REST. We believe there is a path to evolve, clarify, and expand existing functionality in a way that better serves the community, without diminishing or disrupting what already exists.

Differentiate options & use cases

We have work ahead of us to more clearly document and differentiate our APIs and intended use cases. All of the listening tour participants expressed confusion about the differences between the REST and Action APIs, or when one should be used over the other in instances where they offer similar capabilities. To re-emphasize this point, nearly ⅔ (59%) of developer satisfaction survey respondents also disagreed with the statement “It’s clear which endpoint or API I should use; they are easy to differentiate.” This suggests that we have an opportunity to improve the clarity of what is available, as well as provide more opinionated guidance for when one solution should be used instead of or in parallel with another. For example, in high volume situations we may recommend using the REST API over the Action API as a more performant and sustainable solution.

Missing data points

Although 86% of developer satisfaction survey respondents agreed with the statement “the endpoints return data in a format that is usable for me,” gaps still exist that are worth filling in. In a little less than half of the listening tour interviews, developers expressed the need for workarounds to account for missing or mismatched data. For example, in some cases where a specific data point was missing, developers worked around it by pulling data from dumps to supplement what is available in the API. Similarly, there were several complaints about the API not offering the full functionality of what is available in the UI, such as missing filter options for recent changes. Finally, one of the most common complaints for volunteer developers (and particularly those working across Wikipedia and Wikidata) is the inconsistency of available data points across APIs, which require additional parsing, transformation, or supplemental requests to effectively work across them. As we look towards the future, we will pay particularly close attention to these scenarios, where shared data models and complete definitions will better enable creativity and increase the rate of delivery for our developers.

Bulk use cases

Long-time technical volunteers voiced the need to improve support for bulk and batch updates. Tools and scripts are frequently requested with bulk updates in mind. Examples include updating category tags across article or image hierarchies, or editing articles in bulk for grammatical or stylistic issues. However, once these changes are applied, it can be difficult to appropriately moderate the changes. Particularly in cases when something goes wrong with the editing process, every page must be manually reviewed and reverted since there is no tag that associates all the changes with the same bot or backend transaction. This resulted in artificially limiting bulk, programmatic changes, as the scale at which articles can be processed and edited programmatically is orders of magnitude faster than what can reasonably be expected of moderators. We have the opportunity to address this aspect of building trust and tooling for change management, as well as offering more out-of-the-box solutions and endpoints for performing bulk changes that serve the community.

New developer onboarding ramp

In addition to our initial set of listening tour participants being long-time volunteers, over half (55%) of developer satisfaction survey respondents have used Wikimedia APIs for 5+ years. While this suggests that developers are likely to stick around once they get involved and that it is great to have such a big group of long tenured technical Wikimedians, it also suggests that there might be issues at the top of the onboarding funnel. This hypothesis that new developers may get stuck or drop out before contributing was anecdotally confirmed through conversations with newer members of the Wikimedia technical community. While the interviewees eventually figured out what they wanted to do, nearly all of the technical volunteers interviewed confirmed that they had seen many younger or less experienced developers hit a roadblock and give up before launching their initial tool(s). There are countless ways to make onboarding easier for new developers (as well as ramp up feature delivery speed for experienced developers). A few of the key potential focus areas captured through the listening tour are outlined below.

Asking humans for help

The sheer volume of on-wiki API documentation can be a bit overwhelming, and it frequently assumes a high degree of pre-existing knowledge to understand the content. In addition to requests for simplified self-service documentation and code samples, a common sentiment that arose is that it’s easier to either ask someone for help, or find an example to copy instead of attempting to build something from scratch. At the foundation, we have the benefit of working alongside colleagues with ample experience and with a code base full of examples. Volunteers do not come in pre-equipped with those assets, but do frequently seek them out through the various gathering areas and sub-communities. To aid in this journey, we want to make the existing communities more easily discoverable, and help developers navigate across communities by setting expectations for what solutions should be used, when. We also see an opportunity for the Foundation (and volunteers!) to create and publish more comprehensive and discoverable code samples to help new developers get started.

Modern & consistent documentation  

In addition to finding relevant sample code, a primary way that developers are able to navigate the complexity and understand the unique structure is by making test calls in the Action API Sandbox. The Action API Sandbox was called out in a majority of interviews as being the best feature of the Wikimedia API ecosystem. Similarly, the most requested feature coming out of the developer satisfaction survey was better coverage for OpenAPI spec definitions and interactive sandbox documentation for all Wikimedia APIs. With that in mind, we see an opportunity to create a common Sandbox that is backed by OpenAPI specs, supports navigation and discovery across our API portfolio, and delivers interactive API reference documentation in a standard format.

Complementary frameworks

The Action API is powerful, robust, and largely offers comprehensive coverage for Wikimedia projects. However, every new (<=5 years experience) developer that we spoke with shared similar anecdotes about seeing and using the Action APIs for the first time – to use a direct quote from a participant who captured it well, “Whoa, that’s a lot, and it’s nothing like I’ve ever seen before.” New developers universally said that although they eventually figured out what they needed to do, they were thrown off by the structure and format of the Action API and wished that there was more support and coverage for standard frameworks, like REST or GraphQL. While we have no intention of replacing the Action API as it exists today, we do see an opportunity to experiment with wrapping the Action API capabilities in a more modern format to offer alternative experiences for those who prefer working with more familiar frameworks.

API publishing & technical sustainability

In addition to consulting with members of the technical volunteer community, the listening tour included staff members from across the Foundation to learn more about the pain points facing developers who are publishing and managing APIs within our infrastructure. We have the opportunity to improve the developer experience for API publishers and owners, so that they may better deliver and manage their unique capabilities.

Common infrastructure and patterns

Over the years, API publishers have spun up their own infrastructure (e.g., API gateway) and defined their own standards for common API notions (e.g., error messages, pagination). While these deviations were informed best practices of the time, it resulted in disjointed experiences across specific actions and endpoints. The lack of well-defined standards makes it more difficult for API publishers to build and maintain their API offerings. This approach also exposes differing implementation details to developers using the APIs, which can be confusing and time consuming for developers to navigate. Nearly all API publishers stated that they would prefer to use standard pathways and common structures, if available.

Versioning & deprecation

Wikimedia staff is stretched thin, with most teams balancing a mountain of responsibilities. Nearly every internal team called out the need for more standardized processes and tools to support targeted API versioning and deprecation, to start streamlining our offerings into a pile they can reasonably support. API owners should be able to control when a new version is required, and API consumers should know what to expect when big changes such as new versions or endpoint deprecations are required. Today, multiple standards for versioning and deprecation policies are published across different APIs, and some are lacking standards entirely. All Wikimedia developers would benefit from more well defined requirements, processes, and tooling that supports these types of changes.

Communicating changes

69% of developer satisfaction survey participants agreed that announced breaking change and deprecation cycles are long enough. Similarly, all listening tour participants agreed that by and large the Foundation proactively announces changes and allows for ample time to respond to the change. However, all volunteer participants expressed frustration at missed messages and unexpected outages. Although changes are announced through email distribution lists and WikiTech News, they are easy to overlook or forget. Then, due to the diversity of channels coupled with a high volume of announcements and requests coming through some of those channels, notices are frequently forgotten and difficult to rediscover. API developers would like to see improved mechanisms for managing and communicating changes, such as API changelogs and standardized warnings on deprecated response bodies.

Conclusion

To wrap up this year (FY2425), we are collating listening tour learnings with industry trends and Wikimedia’s strategic pillars. This effort will result in an API strategy document that we will use to guide our API evolution. A summary of the strategy will be published on-wiki, along with additional planning resources to outline where we’re heading. Direct quotes from this listening tour were also used in the Future of Wikimedia APIs session conducted at the 2025 Wikimedia Hackathon.

Acknowledgements

Thank you to everyone who participated in this specific listening tour! We deeply appreciate the time and effort you put into answering our questions, and wouldn’t be able to improve the experience for all developers without you. We also look forward to collaborating with more members of the technical community to continue building our path forward together.