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 <[email protected]> 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-KOJNrwRqDsO0k/edit?tab=t.0 > and > https://docs.google.com/spreadsheets/d/1d8fsneiSdCweshV-xEPWQuV8E9jgLm7l6NHpHwN6_cA/edit?gid=0#gid=0 > 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 < > [email protected]> 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 >> <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 -- [email protected] >> To unsubscribe send an email to [email protected] >> >> https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/ > >
_______________________________________________ Wikitech-l mailing list -- [email protected] To unsubscribe send an email to [email protected] https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
