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 < [email protected]> 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 < > [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, 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 -- [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/
