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 < [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/ >
_______________________________________________ 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/
