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/
