Hello guys,

sorry for not replying earlier.

The following is partially taken from my reply to https://bugzilla.wikimedia.org/show_bug.cgi?id=41837 due to some overlapping in the questions/feedback, ultimately it would be great to keep on discussing in this thread.

As a developer I understand your concerns so I'd like to clarify on an important detail: the new API proposal me and it's not necessarily about re-writing the current API (one would argue that "API rewrite", the title of the page on MW.org, doesn't really help from this perspective and if that is the wording also in the kickoff notes, then those are inaccurate as notes taken while people was brainstorming/discussing can usually be), it's about creating a new one using a totally different design for an "high REST service" ("internet scale REST" to use Daniel's words) using the ROA approach (since REST, like OOP, is a design criteria and ROA is an actual architectural design), just to say: since REST is protocol agnostic, we're inquiring alternate transport protocols as an addition to HTTP(S) too, with the side goal/benefit of making MediaWiki a fully

programmable (not-only-web) service.

Starting afresh will let us structure the whole thing with some built-in features that are not easy (at times almost impossible) to embed in the current API, such as authentication (OAuth), performance (caching, hiphop compliance), stability (versioning, i.e. no more mass transitions), accessibility (Service Description Language, automated docs based on PHPDoc, normalized URI's, data schema, existing REST client libraries), quality (unit tests) and re-usability (we're figuring out a way to use the API classes for developing MediaWiki extensions without the mediation of FauxRequest) just to mention a few.

Those have been recognized as improvements upon the current situation during the meeting between the Foundation and Wikia; of course there might be challenges ahead, but that's why we decided to cooperate and learn from each other's experiences; we have been working with 3rd party application developers which had issues reconciling their frameworks (most of which, for coincidence, were REST-compliant) with our API offering (at Wikia we run MediaWiki, currently 1.19) since, to use the words of a MW developer, "right now our docs, client libraries, Sandbox are all mediocre" (https://www.mediawiki.org/wiki/API/API_rewrite/Kickoff_meeting#Design_thoughts), especially when compared to the offerings of other web-based services. During the kickoff meeting both Wikia's and the Foundation developers have expressed some frustration when developing mobile products using the current API (the clients being specifically in the mobile area is just a result of the fact both the organization aren't investing in other areas, like desktop, at the moment and doesn't mean the proposal is meant just to address the needs of mobile developers), which has served the platform well for ~6 years, but in 2012 the web-services landscape has changed a lot and new standards/architectures have been established, around them a rich ecosystem of libraries, frameworks and clients has flourished and this is something that cannot be ignored for too long.

MediaWiki, as a platform, has introduced some great new things in the last 3 releases (RequestContext and ResourceLoader just to name a couple of them), most have modernized the code-base while also delivering some improvements, this proposal is no different although we agreed together to go through the process of producing a formal document which will describe everything in detail (RFC) before making further steps.

During the same meeting a possible transition proposal has been mentioned ("Legacy support for a while.... maybe support and keep updating the old one while building the new one. New endpoint, not backwards-compatible.", to use the exact wording from the notes), this is something which doesn't fall into the domain of the RFC work we've started recently; there are benefits and problems that should be analyzed from many different perspectives in both keeping and deprecating the current API (e.g. breaking old clients, updating/refactor code, authentication via keys, maintaining both versions, quotas, performance/caching in no specific order and grouping) and overall that process is not presented as a goal.

TL;DR: a new API proposal doesn't necessarily mean a death sentence for MW's API; an RFC, when ready, will be published and will represent just the research work done by Wikia in cooperation with the Foundation to see where this idea can lead MediaWiki as a programmable service/platform.

All your feedback is greatly appreciated (especially what you think is good/bad in the current solution, what you would like to see being added/removed/done differently), this is all information that is extremely valuable at this time as it can help us in designing a better solution, but let's avoid focusing just on the "old vs new" argument in the fear we'll have to update the current set of clients which is actually a detail on which the Foundation and Wikia might take a different approach (please consider that both the organizations have a number of bots and apps using the current API, so we understand what a transition could mean to developers).

Federico "Lox" Lucignano

Senior Lead Engineer - Mobile Team

Wikia sp.z.o.o.

email: federico@wikia-inc.com

web: Lox-o-Drome