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/
