Hello and happy Friday!
An API Strategy Brief is now published on mediawiki.org: https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Stra...
This strategy brief covers the direction we're taking Wikimedia's API ecosystem over the next few years, including touching on topics like: why APIs are so important for powering the future of Wikimedia projects, how the current landscape has grown fragmented and hard to navigate, what we're doing to make it more consistent and better documented, and where community developers fit in.
The strategy is written for and applies to anyone building on top of Wikimedia APIs https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Personas, not just internal teams. This strategy was also predominantly informed by conversations with Wikimedian developers through Listening Tours, Hackathon engagements, and more, so I'd like to continue that trend and make sure our strategy reflects what the community actually needs.
If you have thoughts, questions, or concerns, please feel free to post to the talk page, or message me directly via email, Discord, Telegram, smoke signals, or however else you'd like to get in touch.
Thanks! Halley
[PS]: I am also starting to work on a companion doc that goes deeper into our AI + API strategy, specifically. If that's a space that interests you, or if you increasingly feel like you identify as a 'vibe coder', I'd love to talk! :) Feel free to grab time on my calendar https://calendar.app.google/B6SBKQVgK7CQ8VXy9, send your thoughts through email, or comment on the talk page for the API Strategy Brief.
*Halley Coplin* (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation https://wikimediafoundation.org/
I feel like I disagree with the document on multiple things at multiple levels; I try to outline them below:
- *Well-structured, machine-readable documentation is therefore a prerequisite for a good developer experience. ... it is increasingly an AI usability problem, too*.* - *As a human using the ecosystem and an existing stakeholder, I do not think we should be spending any money on making our docs AI-agent readable or have any strategy which prioritizes AI agents over humans. AI agents in our strategy should be, at best, a second-class citizen to our "human knowledge prioritizing" ecosystem. Personally, I think we probably should actually be somewhat disapproving and discourage the extensive use of AI tools (especially if done so without reading our docs, policies, and engaging with the community) within the Wikimedia spaces. (This is not to say judicious use should not be permitted, but folks who build exclusively with AI who expect others to clean up their submitted code or have incorrect assumptions about our community fuelled by hallucinations will damage the community health and culture in the long run)
- *Building developer experiences on top of OpenAPI specs also improves discoverability and accuracy for both search engines and agentic AI tools - *I personally don't understand why we are focusing on making our APIs "machine-readable" when we aren't even good at making them user-readable. For what it's worth, I've worked with agentic AI systems a fair bit as part of my IRL research work, and my overwhelming understanding has been that the AI agents will consume anything written in a human-readable format (which the Action API already has). If anything, I see a move to OpenAPI specifications as alienating human volunteers, who cannot read the JSON outputs and will need to relearn these new patterns from scratch with much less documentation to help.
- *Developer account creation is growing at ~7% annually, but 55% of active contributors have 5+ years of Wikimedia experience. -* I'm fairly certain that whatever the answer to this question is, it isn't "have better APIs". I've talked with a lot of folks regarding why technical contributors keep dropping off, and the answer keeps revolving around "lack of code review", "lack of uptake of tools", "inability to identify high-impact areas", "Gerrit is unwelcoming" and "Phabricator is unwelcoming". For what it's worth, I've explicitly argued for WMF investment to make the volunteer code-review process smoother, but my understanding is that WMF P&T doesn't want to invest in this area this fiscal year, and from what little I have seen, there has been backsliding in terms of willingness to support independent volunteer developers. Personally, I don't see how investing in making our APIs easier to use will help us move the needle on this metric, and it feels like we are trying to find the diamond we lost in the house in the lawn.
-* instead, we offer open access with low limits to all developers, with the option for higher access tiers. *- I don't think gating access to free knowledge is compatible in the slightest with our movement values. Having "tiered" access such that the basic levels upsell you on getting access to "higher tiers" provided you have a relationship with the Foundation (volunteer or Enterprise) feels transactional in a way I don't think Wikimedia has ever seen. This is not to mention that right now the mechanism of getting access to these higher limits is opaque to volunteers and well-meaning reusers, with a giant "look, Wikimedia Enterprise is easier" sign plastered at every corner.
- *If momentum continues, GraphQL could expand as a modernized alternative for Action API queries and generators to further the modernization effort.* * - *GraphQL has multiple major architectural security and scaling issues (OWASP https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html, Portswigger https://portswigger.net/web-security/graphql, Apollo GraphQL https://www.apollographql.com/tutorials/dataloaders-dgs/02-the-n-plus-1-problem) that require significant engineering effort and potentially a complete redesign of the MediaWiki stack, since handling large or complex queries will require federated or distributed architectures and extremely careful thought about how every single schema interoperates with each other, which seems incompatible with the "multiple team SLO" model that this document espouses. As such, I would not recommend pursuing GraphQL any further than as an alternative to unrestricted large datasets such as those already queryable using SPARQL (i.e., in a race between SPARQL and GraphQL, GraphQL would probably win, but both of them would place last when compared with the Action API or the REST API). I see learning GraphQL as an unnecessary burden for both end users (who are familiar with REST and the Action API) and the developers of those APIs, who will now have a significant burden of understanding the scaling semantics associated with the surface they design.
- *Where functional overlap exists, each case needs to be examined for its original intent and current user base to determine whether both solutions are still necessary ... - *I think I have said this multiple times to multiple people, but: *every single volunteer who needs to access Enterprise for their volunteer work (free or otherwise) signals a red-line failure metric telling us we are doing something wrong. *Wikimedia Enterprise is a for-profit entity whose interests are not currently aligned towards performing community-oriented feature requests and tasks. They want to help their larger customers, which typically (to my understanding) are large reusers like Google and OpenAI, and require a subscription model beyond a certain usage threshold (they do have an exception for volunteers, but I have yet to see volunteers engage or be approved through it). A removal of free alternatives (as the text proposes) and a push towards an organization where the community has very little say on API structure is an erosion of multiple promises made to the community that this would never come to pass and is, in my opinion, could be seen as an adversarial action against volunteer reusers of the API.
- *We aim to minimize disruption through significant community engagement and migration support for any mandatory changes. -*My experience with this has been that the WMF has been unwilling to maintain third-party tooling in any way, shape, or form. Multiple breakages have resulted from the recent image-rendering-related changes, and every time the changes come up, WMF folks tell me tool users are on their own, must figure out how to migrate the tool, and that they cannot do anything. (Even when the maintainer of said tool is clearly inactive). The tool ecosystem as it currently stands is extremely fragile, and the community is waaay too dependent on it for there to be no consequences to large-scale changes such as those being proposed (migration towards REST-based endpoints), and I remain extremely concerned that what we are saying here is "yeah so we are gonna prioritize velocity and break critical community infrastructure with an empty offer to help if needed".
- *Support the notion of protected and **internal endpoints for WMF applications**, allowing more flexibility for data access and iteration - *I think this was brought up during a prior Discord call, and the resounding answer that I heard was "no, absolutely not". To put it mildly, a WMF-only endpoint signals "back off; we don't want to collaborate". WMF-only endpoints that volunteers can't call should just never exist, period. I strongly believe that if an API is provided, it should be available to all volunteers and staff. Private endpoints for WMF-only use are not how Wikimedia ever worked, and should never work this way. The software we use is developed collaboratively by volunteers and WMF staff, and taking away/alienating a volunteer's ability to experiment, build on, and improve Foundation UI and APIs is a significant step back from our free and open-source values that encourage tinkering, being bold, and experimenting when building tools.
- *The Action API, which uses an RPC style architecture, supports most internal features and workflows, and it covers use cases that do not fit the REST paradigm. -* I do not like how this document takes a "if we could throw it away we 100% would" approach to the Action API. I think, in practice, the Action API is fairly easy to use once you wrap your head around some specific quirks in its structure. It's surprisingly ergonomic and fairly easy to use (even more so with an SDK wrapper like Pywikibot). In my experience, the REST API has far less documentation and is much less ergonomic and predictable to work with because of its "siloed" nature, which encourages teams to build custom interfaces to accept similar data. This is bad enough that I would personally actually support getting rid of the REST API entirely and shifting to using only the Action API for now and then investing in cross-language SDKs to help "vibe coder" folks get started if they really want to get started using AI to program (cause in my experience, AI agents like having examples and strong types more than any kind of online documentation actually).
- *Some core API methods (eg: parse) have completely bespoke implementations rather than sharing logic with UI features, whereas others (eg: edit page) are intertwined with UI concepts to the point of being nonsensical for an API. - *As somebody who has used these APIs for a significant amount of time, vehemently disagree with these statements. The parse and the edit APIs are ones that I've probably used the most, and I don't see either of these APIs' designs as being obstructive to my workflow. Heck, I've never ever hit the "UI logic" features that this doc says are nonsensical. If anything, the documentation is really rich for these two APIs, and it makes it really easy to visualize/reason about them. (Compared to, say, the recently designed TA account REST API, which took me the better part of a day to decipher when it came out despite being written in the REST paradigm)
P.S: https://docs.google.com/document/d/10elWFA_DZi8JZ8Cic3gORzTSvPZui-KOJNrwRqDs... and https://docs.google.com/spreadsheets/d/1d8fsneiSdCweshV-xEPWQuV8E9jgLm7l6NHp... referenced in this document appear to be unavailable to the broader community.
Regards, Sohom Datta --- Open-source contributor @Wikimedia
On Fri, Aug 28, 2026 at 3:36 PM Halley Coplin via Wikitech-l < wikitech-l@lists.wikimedia.org> wrote:
Hello and happy Friday!
An API Strategy Brief is now published on mediawiki.org: https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Stra...
This strategy brief covers the direction we're taking Wikimedia's API ecosystem over the next few years, including touching on topics like: why APIs are so important for powering the future of Wikimedia projects, how the current landscape has grown fragmented and hard to navigate, what we're doing to make it more consistent and better documented, and where community developers fit in.
The strategy is written for and applies to anyone building on top of Wikimedia APIs https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Personas, not just internal teams. This strategy was also predominantly informed by conversations with Wikimedian developers through Listening Tours, Hackathon engagements, and more, so I'd like to continue that trend and make sure our strategy reflects what the community actually needs.
If you have thoughts, questions, or concerns, please feel free to post to the talk page, or message me directly via email, Discord, Telegram, smoke signals, or however else you'd like to get in touch.
Thanks! Halley
[PS]: I am also starting to work on a companion doc that goes deeper into our AI + API strategy, specifically. If that's a space that interests you, or if you increasingly feel like you identify as a 'vibe coder', I'd love to talk! :) Feel free to grab time on my calendar https://calendar.app.google/B6SBKQVgK7CQ8VXy9, send your thoughts through email, or comment on the talk page for the API Strategy Brief.
*Halley Coplin* (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation https://wikimediafoundation.org/ _______________________________________________ Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org To unsubscribe send an email to wikitech-l-leave@lists.wikimedia.org https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
Hi there,
Just realized that I replied directly to Sohom instead of using "reply all" on Monday. Sorry about that!
To ensure that folks are aware, I added a new FAQ page https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Strategy_Brief/FAQ to the API Strategy Brief https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Strategy_Brief to respond to many of these and other questions related to the brief.
Please take a look, and keep the questions coming! I would love to keep the conversation going.
Cheers, Halley
*Halley Coplin* (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation https://wikimediafoundation.org/
On Sat, Aug 29, 2026 at 8:06 PM Sohom Datta dattasohom1@gmail.com wrote:
I feel like I disagree with the document on multiple things at multiple levels; I try to outline them below:
- *Well-structured, machine-readable documentation is therefore a
prerequisite for a good developer experience. ... it is increasingly an AI usability problem, too*.* - *As a human using the ecosystem and an existing stakeholder, I do not think we should be spending any money on making our docs AI-agent readable or have any strategy which prioritizes AI agents over humans. AI agents in our strategy should be, at best, a second-class citizen to our "human knowledge prioritizing" ecosystem. Personally, I think we probably should actually be somewhat disapproving and discourage the extensive use of AI tools (especially if done so without reading our docs, policies, and engaging with the community) within the Wikimedia spaces. (This is not to say judicious use should not be permitted, but folks who build exclusively with AI who expect others to clean up their submitted code or have incorrect assumptions about our community fuelled by hallucinations will damage the community health and culture in the long run)
- *Building developer experiences on top of OpenAPI specs also improves
discoverability and accuracy for both search engines and agentic AI tools
- *I personally don't understand why we are focusing on making our APIs
"machine-readable" when we aren't even good at making them user-readable. For what it's worth, I've worked with agentic AI systems a fair bit as part of my IRL research work, and my overwhelming understanding has been that the AI agents will consume anything written in a human-readable format (which the Action API already has). If anything, I see a move to OpenAPI specifications as alienating human volunteers, who cannot read the JSON outputs and will need to relearn these new patterns from scratch with much less documentation to help.
- *Developer account creation is growing at ~7% annually, but 55% of
active contributors have 5+ years of Wikimedia experience. -* I'm fairly certain that whatever the answer to this question is, it isn't "have better APIs". I've talked with a lot of folks regarding why technical contributors keep dropping off, and the answer keeps revolving around "lack of code review", "lack of uptake of tools", "inability to identify high-impact areas", "Gerrit is unwelcoming" and "Phabricator is unwelcoming". For what it's worth, I've explicitly argued for WMF investment to make the volunteer code-review process smoother, but my understanding is that WMF P&T doesn't want to invest in this area this fiscal year, and from what little I have seen, there has been backsliding in terms of willingness to support independent volunteer developers. Personally, I don't see how investing in making our APIs easier to use will help us move the needle on this metric, and it feels like we are trying to find the diamond we lost in the house in the lawn.
-* instead, we offer open access with low limits to all developers, with the option for higher access tiers. *- I don't think gating access to free knowledge is compatible in the slightest with our movement values. Having "tiered" access such that the basic levels upsell you on getting access to "higher tiers" provided you have a relationship with the Foundation (volunteer or Enterprise) feels transactional in a way I don't think Wikimedia has ever seen. This is not to mention that right now the mechanism of getting access to these higher limits is opaque to volunteers and well-meaning reusers, with a giant "look, Wikimedia Enterprise is easier" sign plastered at every corner.
- *If momentum continues, GraphQL could expand as a modernized
alternative for Action API queries and generators to further the modernization effort.* * - *GraphQL has multiple major architectural security and scaling issues (OWASP https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html, Portswigger https://portswigger.net/web-security/graphql, Apollo GraphQL https://www.apollographql.com/tutorials/dataloaders-dgs/02-the-n-plus-1-problem) that require significant engineering effort and potentially a complete redesign of the MediaWiki stack, since handling large or complex queries will require federated or distributed architectures and extremely careful thought about how every single schema interoperates with each other, which seems incompatible with the "multiple team SLO" model that this document espouses. As such, I would not recommend pursuing GraphQL any further than as an alternative to unrestricted large datasets such as those already queryable using SPARQL (i.e., in a race between SPARQL and GraphQL, GraphQL would probably win, but both of them would place last when compared with the Action API or the REST API). I see learning GraphQL as an unnecessary burden for both end users (who are familiar with REST and the Action API) and the developers of those APIs, who will now have a significant burden of understanding the scaling semantics associated with the surface they design.
- *Where functional overlap exists, each case needs to be examined for
its original intent and current user base to determine whether both solutions are still necessary ... - *I think I have said this multiple times to multiple people, but: *every single volunteer who needs to access Enterprise for their volunteer work (free or otherwise) signals a red-line failure metric telling us we are doing something wrong. *Wikimedia Enterprise is a for-profit entity whose interests are not currently aligned towards performing community-oriented feature requests and tasks. They want to help their larger customers, which typically (to my understanding) are large reusers like Google and OpenAI, and require a subscription model beyond a certain usage threshold (they do have an exception for volunteers, but I have yet to see volunteers engage or be approved through it). A removal of free alternatives (as the text proposes) and a push towards an organization where the community has very little say on API structure is an erosion of multiple promises made to the community that this would never come to pass and is, in my opinion, could be seen as an adversarial action against volunteer reusers of the API.
- *We aim to minimize disruption through significant community engagement
and migration support for any mandatory changes. -*My experience with this has been that the WMF has been unwilling to maintain third-party tooling in any way, shape, or form. Multiple breakages have resulted from the recent image-rendering-related changes, and every time the changes come up, WMF folks tell me tool users are on their own, must figure out how to migrate the tool, and that they cannot do anything. (Even when the maintainer of said tool is clearly inactive). The tool ecosystem as it currently stands is extremely fragile, and the community is waaay too dependent on it for there to be no consequences to large-scale changes such as those being proposed (migration towards REST-based endpoints), and I remain extremely concerned that what we are saying here is "yeah so we are gonna prioritize velocity and break critical community infrastructure with an empty offer to help if needed".
- *Support the notion of protected and **internal endpoints for WMF
applications**, allowing more flexibility for data access and iteration - *I think this was brought up during a prior Discord call, and the resounding answer that I heard was "no, absolutely not". To put it mildly, a WMF-only endpoint signals "back off; we don't want to collaborate". WMF-only endpoints that volunteers can't call should just never exist, period. I strongly believe that if an API is provided, it should be available to all volunteers and staff. Private endpoints for WMF-only use are not how Wikimedia ever worked, and should never work this way. The software we use is developed collaboratively by volunteers and WMF staff, and taking away/alienating a volunteer's ability to experiment, build on, and improve Foundation UI and APIs is a significant step back from our free and open-source values that encourage tinkering, being bold, and experimenting when building tools.
- *The Action API, which uses an RPC style architecture, supports most
internal features and workflows, and it covers use cases that do not fit the REST paradigm. -* I do not like how this document takes a "if we could throw it away we 100% would" approach to the Action API. I think, in practice, the Action API is fairly easy to use once you wrap your head around some specific quirks in its structure. It's surprisingly ergonomic and fairly easy to use (even more so with an SDK wrapper like Pywikibot). In my experience, the REST API has far less documentation and is much less ergonomic and predictable to work with because of its "siloed" nature, which encourages teams to build custom interfaces to accept similar data. This is bad enough that I would personally actually support getting rid of the REST API entirely and shifting to using only the Action API for now and then investing in cross-language SDKs to help "vibe coder" folks get started if they really want to get started using AI to program (cause in my experience, AI agents like having examples and strong types more than any kind of online documentation actually).
- *Some core API methods (eg: parse) have completely bespoke
implementations rather than sharing logic with UI features, whereas others (eg: edit page) are intertwined with UI concepts to the point of being nonsensical for an API. - *As somebody who has used these APIs for a significant amount of time, vehemently disagree with these statements. The parse and the edit APIs are ones that I've probably used the most, and I don't see either of these APIs' designs as being obstructive to my workflow. Heck, I've never ever hit the "UI logic" features that this doc says are nonsensical. If anything, the documentation is really rich for these two APIs, and it makes it really easy to visualize/reason about them. (Compared to, say, the recently designed TA account REST API, which took me the better part of a day to decipher when it came out despite being written in the REST paradigm)
P.S: https://docs.google.com/document/d/10elWFA_DZi8JZ8Cic3gORzTSvPZui-KOJNrwRqDs... and https://docs.google.com/spreadsheets/d/1d8fsneiSdCweshV-xEPWQuV8E9jgLm7l6NHp... referenced in this document appear to be unavailable to the broader community.
Regards, Sohom Datta
Open-source contributor @Wikimedia
On Fri, Aug 28, 2026 at 3:36 PM Halley Coplin via Wikitech-l < wikitech-l@lists.wikimedia.org> wrote:
Hello and happy Friday!
An API Strategy Brief is now published on mediawiki.org: https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Stra...
This strategy brief covers the direction we're taking Wikimedia's API ecosystem over the next few years, including touching on topics like: why APIs are so important for powering the future of Wikimedia projects, how the current landscape has grown fragmented and hard to navigate, what we're doing to make it more consistent and better documented, and where community developers fit in.
The strategy is written for and applies to anyone building on top of Wikimedia APIs https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Personas, not just internal teams. This strategy was also predominantly informed by conversations with Wikimedian developers through Listening Tours, Hackathon engagements, and more, so I'd like to continue that trend and make sure our strategy reflects what the community actually needs.
If you have thoughts, questions, or concerns, please feel free to post to the talk page, or message me directly via email, Discord, Telegram, smoke signals, or however else you'd like to get in touch.
Thanks! Halley
[PS]: I am also starting to work on a companion doc that goes deeper into our AI + API strategy, specifically. If that's a space that interests you, or if you increasingly feel like you identify as a 'vibe coder', I'd love to talk! :) Feel free to grab time on my calendar https://calendar.app.google/B6SBKQVgK7CQ8VXy9, send your thoughts through email, or comment on the talk page for the API Strategy Brief.
*Halley Coplin* (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation https://wikimediafoundation.org/ _______________________________________________ Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org To unsubscribe send an email to wikitech-l-leave@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
First of all.
I'm glad to see the API being treated as a product again. I think for a landscape that is as complex as ours, this is critical. Having an overall plan for the next 10 years of implementation seems prudent considering how long the development and deprecation cycle of certain elements can be and the amount of people both external and internal that depend on it.
I will say that I see a lot of argumentation in this brief that while true and related, these API direction are not in and of itself going to be material part of solving most of those problems. I think that is essential to keep in mind and I wish this was better explained in this brief.
I see many of the recommendations in this brief as simply pretty basic engineering practices for web properties.
REST apis allow for easier routing, allows for simple HTTP caching strategies, simpler HTTP level authentication and authorization, distributing to dedicated servers etc. It also has very wide support in various tools via openapi docs, making it easier to interface with tools like Postman, Bruno, but also solutions like API routers. And yes, AIs can use them as well, to do more formal verification of their knowledge, which hopefully leads to less messy and incorrect requests for instance. There are definitely lots of benefits here.
But then I read things like:
"only 44% of developers agree that it is clear which API or endpoint they should use; the landscape is confusing not just because of the number of options, but because of the inconsistencies between them. Addressing this requires both reducing unnecessary complexity and making deliberate, opinionated choices about how our APIs are structured and presented:"
And i think we have to be clear. There is also a LOT of confusion simply because the solutions we build with our APIs are complex and deal with complex problems. We think differently about the web than most organizations. This is a FAR bigger contribution to the confusion than the action api or the distributed nature of the documentation in my opinion. Will having a well developed rest api + openapi docs help with that ? Sure a little bit, but let's not blame the action api for not being able to explain flagged revisions or language variants to a user.
Also we are running multiple APIs in parallel (for at least another 10 years), so will we really be slaying those dragons that way ? I think we can if executed well, but there is no golden goose here.
"Shared business logic: Some core API methods (eg: parse) have completely bespoke implementations rather than sharing logic with UI features, whereas others (eg: edit page) are intertwined with UI concepts to the point of being nonsensical for an API."
True. But things are intertwined for a reason, and it has very little to do with the API design. It is about legacy, lack of attention and the sheer complexity of taking apart something complex that works without breaking things. If the point is, if we are going to be touching things we might as well fix that, sure.
One thing i am missing in this brief, is a view on what goes into APIs. We have: - entities - actions - bulk operations - queries - composited views like PCS (i explain these as queries of entities that form the input for an HTML template you render to show a user) - internal and external information and/or users etc. - 360 websites, custom map and math functionality, subtitles etc etc.
I think it is prudent that we don't just pick a technology, but that we also put thought into how and when we then fill out this technology with what we have. This requires writing this in developer documentation before we just start. That avoids us building a REST api that simply transfers the complexity of the action api into a REST api. What makes a good API parameter, what a bad one. What goes into a queryparam, and what goes into a path param, how to define a good path for your api. This strategy brief alone is not enough to avoid creating a mess, so i'd like to see these coding guidelines as a deliverable somewhere in the coming year.
I'm also happy to see the mention of GraphQL. GraphQL and REST composite views are competing technology solutions you could say. I think GraphQL is a powerful technology but I do have some reservations from personal experience. GraphQL makes doing a lot of the things that REST API excels at (edge layer checks, logging) very different. Instead of optimizing a webserver, you are optimizing a query engine, meaning that your checks on the internal side need to be stronger. Additionally, core developers are not as used to writing endpoints that are consumed by GraphQL. I've seen at least two mess ups with authorization in GraphQL apis that were caused by people not realizing their collection was in a GraphQL api to begin with.
Lastly, we should not underestimate the additional overhead of having two APIs.
That's my feedback.
On 28 Aug 2026, at 21:34, Halley Coplin via Wikitech-l wikitech-l@lists.wikimedia.org wrote:
Hello and happy Friday! An API Strategy Brief is now published on mediawiki.org: https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Stra... This strategy brief covers the direction we're taking Wikimedia's API ecosystem over the next few years, including touching on topics like: why APIs are so important for powering the future of Wikimedia projects, how the current landscape has grown fragmented and hard to navigate, what we're doing to make it more consistent and better documented, and where community developers fit in. The strategy is written for and applies to anyone building on top of Wikimedia APIs, not just internal teams. This strategy was also predominantly informed by conversations with Wikimedian developers through Listening Tours, Hackathon engagements, and more, so I'd like to continue that trend and make sure our strategy reflects what the community actually needs. If you have thoughts, questions, or concerns, please feel free to post to the talk page, or message me directly via email, Discord, Telegram, smoke signals, or however else you'd like to get in touch. Thanks! Halley
[PS]: I am also starting to work on a companion doc that goes deeper into our AI + API strategy, specifically. If that's a space that interests you, or if you increasingly feel like you identify as a 'vibe coder', I'd love to talk! :) Feel free to grab time on my calendar, send your thoughts through email, or comment on the talk page for the API Strategy Brief.
Halley Coplin (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation _______________________________________________ Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org To unsubscribe send an email to wikitech-l-leave@lists.wikimedia.org https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
I feel like we dont really care about ease of caching that much, as action api's CDN caching support has been (partially) broken at wikimedia for a while now and nobody seems that eager to fix it.
Personally I don't like the REST api. I think the action api is much better designed and the introduction of the REST api has been very confusing to users.
-- Brian
On Saturday, 5 September 2026, Derk-Jan Hartman via Wikitech-l < wikitech-l@lists.wikimedia.org> wrote:
First of all.
I'm glad to see the API being treated as a product again. I think for a landscape that is as complex as ours, this is critical. Having an overall plan for the next 10 years of implementation seems prudent considering how long the development and deprecation cycle of certain elements can be and the amount of people both external and internal that depend on it.
I will say that I see a lot of argumentation in this brief that while true and related, these API direction are not in and of itself going to be material part of solving most of those problems. I think that is essential to keep in mind and I wish this was better explained in this brief.
I see many of the recommendations in this brief as simply pretty basic engineering practices for web properties.
REST apis allow for easier routing, allows for simple HTTP caching strategies, simpler HTTP level authentication and authorization, distributing to dedicated servers etc. It also has very wide support in various tools via openapi docs, making it easier to interface with tools like Postman, Bruno, but also solutions like API routers. And yes, AIs can use them as well, to do more formal verification of their knowledge, which hopefully leads to less messy and incorrect requests for instance. There are definitely lots of benefits here.
But then I read things like:
"only 44% of developers agree that it is clear which API or endpoint
they should use; the landscape is confusing not just because of the number of options, but because of the inconsistencies between them. Addressing this requires both reducing unnecessary complexity and making deliberate, opinionated choices about how our APIs are structured and presented:"
And i think we have to be clear. There is also a LOT of confusion simply because the solutions we build with our APIs are complex and deal with complex problems. We think differently about the web than most organizations. This is a FAR bigger contribution to the confusion than the action api or the distributed nature of the documentation in my opinion. Will having a well developed rest api + openapi docs help with that ? Sure a little bit, but let's not blame the action api for not being able to explain flagged revisions or language variants to a user.
Also we are running multiple APIs in parallel (for at least another 10 years), so will we really be slaying those dragons that way ? I think we can if executed well, but there is no golden goose here.
"Shared business logic: Some core API methods (eg: parse) have
completely bespoke implementations rather than sharing logic with UI features, whereas others (eg: edit page) are intertwined with UI concepts to the point of being nonsensical for an API."
True. But things are intertwined for a reason, and it has very little to do with the API design. It is about legacy, lack of attention and the sheer complexity of taking apart something complex that works without breaking things. If the point is, if we are going to be touching things we might as well fix that, sure.
One thing i am missing in this brief, is a view on what goes into APIs. We have:
- entities
- actions
- bulk operations
- queries
- composited views like PCS (i explain these as queries of entities that
form the input for an HTML template you render to show a user)
- internal and external information and/or users etc.
- 360 websites, custom map and math functionality, subtitles etc etc.
I think it is prudent that we don't just pick a technology, but that we also put thought into how and when we then fill out this technology with what we have. This requires writing this in developer documentation before we just start. That avoids us building a REST api that simply transfers the complexity of the action api into a REST api. What makes a good API parameter, what a bad one. What goes into a queryparam, and what goes into a path param, how to define a good path for your api. This strategy brief alone is not enough to avoid creating a mess, so i'd like to see these coding guidelines as a deliverable somewhere in the coming year.
I'm also happy to see the mention of GraphQL. GraphQL and REST composite views are competing technology solutions you could say. I think GraphQL is a powerful technology but I do have some reservations from personal experience. GraphQL makes doing a lot of the things that REST API excels at (edge layer checks, logging) very different. Instead of optimizing a webserver, you are optimizing a query engine, meaning that your checks on the internal side need to be stronger. Additionally, core developers are not as used to writing endpoints that are consumed by GraphQL. I've seen at least two mess ups with authorization in GraphQL apis that were caused by people not realizing their collection was in a GraphQL api to begin with.
Lastly, we should not underestimate the additional overhead of having two APIs.
That's my feedback.
On 28 Aug 2026, at 21:34, Halley Coplin via Wikitech-l <
wikitech-l@lists.wikimedia.org> wrote:
Hello and happy Friday! An API Strategy Brief is now published on mediawiki.org:
https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_ Strategy_Brief
This strategy brief covers the direction we're taking Wikimedia's API
ecosystem over the next few years, including touching on topics like: why APIs are so important for powering the future of Wikimedia projects, how the current landscape has grown fragmented and hard to navigate, what we're doing to make it more consistent and better documented, and where community developers fit in.
The strategy is written for and applies to anyone building on top of
Wikimedia APIs, not just internal teams. This strategy was also predominantly informed by conversations with Wikimedian developers through Listening Tours, Hackathon engagements, and more, so I'd like to continue that trend and make sure our strategy reflects what the community actually needs.
If you have thoughts, questions, or concerns, please feel free to post
to the talk page, or message me directly via email, Discord, Telegram, smoke signals, or however else you'd like to get in touch.
Thanks! Halley
[PS]: I am also starting to work on a companion doc that goes deeper
into our AI + API strategy, specifically. If that's a space that interests you, or if you increasingly feel like you identify as a 'vibe coder', I'd love to talk! :) Feel free to grab time on my calendar, send your thoughts through email, or comment on the talk page for the API Strategy Brief.
Halley Coplin (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation _______________________________________________ Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org To unsubscribe send an email to wikitech-l-leave@lists.wikimedia.org https://lists.wikimedia.org/postorius/lists/wikitech-l.
lists.wikimedia.org/
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org To unsubscribe send an email to wikitech-l-leave@lists.wikimedia.org https://lists.wikimedia.org/postorius/lists/wikitech-l. lists.wikimedia.org/
Thanks for the thoughtful feedback, DJ! I pulled out a few threads here to respond inline, and I’ll figure out what's worth folding into the FAQ for future audiences.
I can also promise you (and everyone else on this thread) that there are a few more explanatory docs in the pipeline that we'll publish on-wiki soon, which I think will address many of your concerns and suggestions. I'm also planning to open an "API Corner" in the English Wikipedia Discord once I'm back from time off later this month, so we have a place for more casual conversation, rapid feedback, and quick questions.
One other note before jumping in: when I say "we" below, I mean the MediaWiki API Platform (formally known as: MediaWiki Interfaces) team, not the Foundation at large (nor the royal we, even though I'm apparently using a rather royal purple for these replies). While I wrote the brief, the thinking and experiments behind it are a team effort with Daniel https://www.mediawiki.org/wiki/User:DKinzler_(WMF), Moriel https://www.mediawiki.org/wiki/User:MSchottlender-WMF, Bill https://www.mediawiki.org/wiki/User:BPirkle_(WMF), Aaron https://www.mediawiki.org/wiki/User:Aaron_Schulz, and others. I hope they don’t mind me speaking on their behalf, and I welcome anyone else on the team to weigh in if you feel so inclined!
I will say that I see a lot of argumentation in this brief that while true and related, these API direction are not in and of itself going to be material part of solving most of those problems.
This is totally fair; updating our existing APIs is only a small part of what the developer community actually needs, as both you and Sohom raised. Neither of you are wrong. The clean up still has to happen though, since the current complexity is a real maintenance burden across the board, and it's getting to the point where it’s preventing us from moving faster.
The API Platform is meant to serve as that force multiplier for the API space specifically. The new API module framework lets teams build, version, and deprecate APIs independently, so changes in one module don't ripple across the ecosystem. On top of that, we're programmatically enforcing shared patterns and guardrails (hosting, naming conventions, object properties, telemetry, etc) so builders aren't reinventing the wheel. Layering this with automated testing to detect API drift creates the right mechanisms to keep things consistent, accurate, clear, and reliable, even as teams start moving more quickly to deliver new APIs for novel features and use cases.
I think it is prudent that we don't just pick a technology, but that we also put thought into how and when we then fill out this technology with what we have. [...] REST api that simply transfers the complexity of the action api into a REST api. What makes a good API parameter, what a bad one. What goes into a queryparam, and what goes into a path param, how to define a good path for your api.
Completely agree, and this is genuinely aligned with what we have planned for implementation. Sorry that didn't come through clearly in the brief itself (noted for future revisions)! There are two things up our sleeve that are coming soon and worth mentioning: 1) a technical design doc from Daniel the goes a bit deeper on how & why we are reimagining the Action API interface (released alongside current functionality, not as a breaking change), and 2) a beta "vNext" API module that shows how we're approaching blended modules in practice (and can actually be called by users like you!). That beta API will touch on things you’re mentioned like consistent pathing, error messages, pagination, naming conventions, and core assumptions for shared entities like page, revision, and user. None of it is locked in yet, so the beta is really there to get feedback from y'all while it's still flexible, since you’re right that whatever we land on now is probably sticking around for a while (maybe even 10 years!), give or take a version here and there.
That being said, we have no intention of replacing the Action API with REST across the board. The goal is matching the right technology to the use case, not picking a winner and forcing everything to that structure. Merging pages, for instance, doesn't fit a REST paradigm cleanly at all, since it’s inherently touching multiple pages and related sub-entities in a single operation. While this will become more clear in the next few weeks when the beta module actually makes it out the door, I can provide a quick concrete preview of the blended "page" module: editing will likely stay as an Action, but exposed as a more REST-like RPC endpoint, since POST/PUT page mechanics don't map cleanly to a single entity anyway (creating a new revisions vs updating a page, handling comments and merge conflicts, etc.). On the flip side, requesting page HTML will shift more holistically toward REST, since the Parse action bypasses the edge cache entirely.
To be extra extra clear, there is also no intention to deprecate, sunset, or replace the current Action API format. We may be a little more proactive on sunsetting some of the REST implementation flavors this year since there are literally 3 versions of effectively the same endpoints and the majority of the traffic is from internal features, but the current Action API will continue to work as-is.
But things are intertwined for a reason, and it has very little to do with the API design.
Also very true. That said, APIs have the opportunity to isolate clients from some of that complexity even when they can't eliminate it. A lot of what developers see today is just the underlying business logic (warts and all) exposed directly. Candidly, as you’re pointing out, some of that is unavoidable as the business logic and implementation is simply ugly and complex and there might not be a good way to simplify it without eroding feature parity. Merge conflicts during editing is a good example of that logic being messy and deeply intertwined with UI-isms. While we will certainly look into ways of improving it, some complexity is likely to remain if we want to maintain API parity. In those cases, we can at least make it a little more straightforward and approachable in structure and documentation, even if it still requires a degree of expertise with Wikimedia practices.
One other pattern we're leaning into to support this is treating APIs more as a facade layer: define a solid interface, and let what's underneath keep evolving, without exposing the full complexity or introducing massive breaking changes along the way.
That's basically what we're exploring with the Action API right now. We're not reimplementing everything, just building a new interface on the existing stack. While we won’t necessarily fix the underlying complexity in all cases, it gives an opportunity to clean the most visible and important things up as we translate each action over. There's a maintenance cost to that, though you could argue the current approach just shifts that cost onto the developer community instead.
One thing i am missing in this brief, is a view on what goes into APIs.
We're starting to dig into this, using the idea of "domains" to decide how endpoints get grouped, balancing independent team ownership against groupings that actually make sense to users rather than just mirroring internal structures. Good call on making some of these assumptions explicit rather than letting them emerge organically, too. The "core" entity definitions I mentioned above are part of the same effort (what's the bare minimum that defines a page, a revision, a user, and making sure that's consistent everywhere) to ensure interoperability across the topics you’ve mentioned, too.
Additionally, core developers are not as used to writing endpoints that are consumed by GraphQL. I've seen at least two mess ups with authorization in GraphQL apis that were caused by people not realizing their collection was in a GraphQL api to begin with.
Daniel touched on this a bit in the FAQ and on-wiki responses to Sohom, but the long story short is that the GraphQL exploration is still very early and limited in its intended scope. Right now we are only experimenting with the Query action through a GraphQL interface, since it does seem to support a direct translation that is both more cacheable and more intuitive for building in the QUERY body than the current implementation. The early experiment will be a topic in the API Corner soon (and likely shared here around the same time), so keep an eye out. Definitely welcome the concerns, questions, and curiosities about GraphQL in general, too.
Anyway, thank you again for the feedback. I didn’t touch on everything, but hopefully this sheds some perspective on your concerns, and opens the door for more curiosity from everyone as we continue to evolve together. I look forward to continuing the conversation here, on-wiki, and/or on Discord too!
Cheers, Halley
PS: I have PTO planned starting this Friday and covering much of the second half of September, so please expect delays in responses for the next few weeks!
*Halley Coplin* (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation https://wikimediafoundation.org/
On Sat, Sep 5, 2026 at 7:43 AM Derk-Jan Hartman < d.j.hartman+wmf_ml@gmail.com> wrote:
First of all.
I'm glad to see the API being treated as a product again. I think for a landscape that is as complex as ours, this is critical. Having an overall plan for the next 10 years of implementation seems prudent considering how long the development and deprecation cycle of certain elements can be and the amount of people both external and internal that depend on it.
I will say that I see a lot of argumentation in this brief that while true and related, these API direction are not in and of itself going to be material part of solving most of those problems. I think that is essential to keep in mind and I wish this was better explained in this brief.
I see many of the recommendations in this brief as simply pretty basic engineering practices for web properties.
REST apis allow for easier routing, allows for simple HTTP caching strategies, simpler HTTP level authentication and authorization, distributing to dedicated servers etc. It also has very wide support in various tools via openapi docs, making it easier to interface with tools like Postman, Bruno, but also solutions like API routers. And yes, AIs can use them as well, to do more formal verification of their knowledge, which hopefully leads to less messy and incorrect requests for instance. There are definitely lots of benefits here.
But then I read things like:
"only 44% of developers agree that it is clear which API or endpoint
they should use; the landscape is confusing not just because of the number of options, but because of the inconsistencies between them. Addressing this requires both reducing unnecessary complexity and making deliberate, opinionated choices about how our APIs are structured and presented:"
And i think we have to be clear. There is also a LOT of confusion simply because the solutions we build with our APIs are complex and deal with complex problems. We think differently about the web than most organizations. This is a FAR bigger contribution to the confusion than the action api or the distributed nature of the documentation in my opinion. Will having a well developed rest api + openapi docs help with that ? Sure a little bit, but let's not blame the action api for not being able to explain flagged revisions or language variants to a user.
Also we are running multiple APIs in parallel (for at least another 10 years), so will we really be slaying those dragons that way ? I think we can if executed well, but there is no golden goose here.
"Shared business logic: Some core API methods (eg: parse) have
completely bespoke implementations rather than sharing logic with UI features, whereas others (eg: edit page) are intertwined with UI concepts to the point of being nonsensical for an API."
True. But things are intertwined for a reason, and it has very little to do with the API design. It is about legacy, lack of attention and the sheer complexity of taking apart something complex that works without breaking things. If the point is, if we are going to be touching things we might as well fix that, sure.
One thing i am missing in this brief, is a view on what goes into APIs. We have:
- entities
- actions
- bulk operations
- queries
- composited views like PCS (i explain these as queries of entities that
form the input for an HTML template you render to show a user)
- internal and external information and/or users etc.
- 360 websites, custom map and math functionality, subtitles etc etc.
I think it is prudent that we don't just pick a technology, but that we also put thought into how and when we then fill out this technology with what we have. This requires writing this in developer documentation before we just start. That avoids us building a REST api that simply transfers the complexity of the action api into a REST api. What makes a good API parameter, what a bad one. What goes into a queryparam, and what goes into a path param, how to define a good path for your api. This strategy brief alone is not enough to avoid creating a mess, so i'd like to see these coding guidelines as a deliverable somewhere in the coming year.
I'm also happy to see the mention of GraphQL. GraphQL and REST composite views are competing technology solutions you could say. I think GraphQL is a powerful technology but I do have some reservations from personal experience. GraphQL makes doing a lot of the things that REST API excels at (edge layer checks, logging) very different. Instead of optimizing a webserver, you are optimizing a query engine, meaning that your checks on the internal side need to be stronger. Additionally, core developers are not as used to writing endpoints that are consumed by GraphQL. I've seen at least two mess ups with authorization in GraphQL apis that were caused by people not realizing their collection was in a GraphQL api to begin with.
Lastly, we should not underestimate the additional overhead of having two APIs.
That's my feedback.
On 28 Aug 2026, at 21:34, Halley Coplin via Wikitech-l <
wikitech-l@lists.wikimedia.org> wrote:
Hello and happy Friday! An API Strategy Brief is now published on mediawiki.org:
https://www.mediawiki.org/wiki/MediaWiki_Product_Insights/Artifacts/API_Stra...
This strategy brief covers the direction we're taking Wikimedia's API
ecosystem over the next few years, including touching on topics like: why APIs are so important for powering the future of Wikimedia projects, how the current landscape has grown fragmented and hard to navigate, what we're doing to make it more consistent and better documented, and where community developers fit in.
The strategy is written for and applies to anyone building on top of
Wikimedia APIs, not just internal teams. This strategy was also predominantly informed by conversations with Wikimedian developers through Listening Tours, Hackathon engagements, and more, so I'd like to continue that trend and make sure our strategy reflects what the community actually needs.
If you have thoughts, questions, or concerns, please feel free to post
to the talk page, or message me directly via email, Discord, Telegram, smoke signals, or however else you'd like to get in touch.
Thanks! Halley
[PS]: I am also starting to work on a companion doc that goes deeper
into our AI + API strategy, specifically. If that's a space that interests you, or if you increasingly feel like you identify as a 'vibe coder', I'd love to talk! :) Feel free to grab time on my calendar, send your thoughts through email, or comment on the talk page for the API Strategy Brief.
Halley Coplin (she/her) Sr. Product Manager, MediaWiki Interfaces Wikimedia Foundation _______________________________________________ Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org To unsubscribe send an email to wikitech-l-leave@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
wikitech-l@lists.wikimedia.org