Hello, Can you please tell us if this API rewrite is backward compatible? I have already done a lot of programming using existing API and I am worried if I need to re-program it all over again. Appreciate you quick response. Thanks, Ravi On Nov 8, 2012, at 4:55 AM, "Federico \"Lox\" Lucignano" <federico(a)wikia-inc.com> wrote:

On 08/11/12 16:17, Chad wrote: I don't think it would be wise to remove the current api. Yes, it may be cool to use a PUT verb for storing wikitext in a page (aka. doing an edit). But we don't want "coolness += 1; utility -= 100;" I'm not opposed to a new branch playing with that concept, but clearly separated, please. Besides, I don't think that new developers look for "Does it have a REST interface?" when deciding if making an application. Things like "Is it well documented?" are much more important, and IMHO we are doing a good job there. Not to mention the fact of having existing libraries, of which we have a good number. If all the other wikis were using a Grand Unified Wiki Api and MediaWiki was at odds using its own one, or there were existing clients which would benefit from that change, it could be considered, but that's not available. Trashing existing documentation, people knowledge and libraries in exchange of a cool concept is a big no-no. Long live the existing api!

Agree. Don't sunset the existing API. It would break my application. --- *The very best place for news about Nimble: *http://www.quora.com/ncp On Thu, Nov 8, 2012 at 11:19 AM, Chad <innocentkiller(a)gmail.com> wrote:

Hi, Same response from me, I don't really understand this need for a new api. The current one is working correctly (at least for me), has enough documentation to let developers find their way for using it, ... I'm currently using a lot of functions from the current API for WPCleaner [1]. I've already done the upgrade from query.php to api.php in its time, and I know that going from one api to an other again would require a lot of my time to implement and test. And without any obvious improvement. Nico [1] http://en.wikipedia.org/wiki/Wikipedia:WPCleaner On Fri, Nov 9, 2012 at 6:11 AM, Chris Grant <chrisgrantmail(a)gmail.com>wrote;wrote:

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_thoug…), 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). On Fri, Nov 9, 2012 at 9:47 PM, Mark Wagner &lt;carnildo(a)gmail.com&gt; wrote: -- --- Federico "Lox" Lucignano Senior Lead Engineer - Mobile Team Wikia sp.z.o.o. email: federico(a)wikia-inc.com web: Lox-o-Drome <http://lox-o-drome.blogspot.com>

Hi Platonides, sorry but I don't see the connection with 927 (funny thing is being such a big fan of Randall I did not even had to look it up :D), if you're referring to the proposal as a whole then what we're trying to do here is to adopt a couple of standards rather than coming up with yet another one. Concerning versioning, despite I agree that no system is able to keep backwards compatibility forever (as any software solution reaches the end of its' lifecycle sooner or later depending on how manageable it is to keep updating/improving it), how you implement versioning in an API is actually a very important factor for ensuring future backwards compatibility: when an hypothetical /rest/v2/xyz resource would be made available, the previous /rest/v1/xyz would be left intact, where the v2 xyz resource could be a direct descendant of v1 to avoid code duplication and simplify maintenance tasks. This is just one of many options, the important thing is to keep versioning into high consideration when designing a new API and that's something we're doing for this proposal. On Sat, Nov 10, 2012 at 5:04 PM, Platonides &lt;platonides(a)gmail.com&gt; wrote: -- --- Federico "Lox" Lucignano Senior Lead Engineer - Mobile Team Wikia sp.z.o.o. email: federico(a)wikia-inc.com web: Lox-o-Drome <http://lox-o-drome.blogspot.com>

Handling wikitext in a structured way is an interesting concept, as far as I know the team working on the new visual editor (another joint project between the Foundation and Wikia) has built a "parsoid" that does something pretty much similar if not the same, that functionality could be exposed as an API resource, for more information feel free to drop them an email (I'm not sure there's a dedicated mailing list). That being said, it would be of great interest to get implementation details about the suggestions focusing on the concept that introducing all the stated goals/benefits/features would be easy without introducing breaking changes, it's unclear on which basis that assessment is done in the complete absence of technical details (all the documentation published so far is made up just of notes listing concepts by name). On a side note, a simpler, normalized URI schema (URL is too restrictive, in the end REST is not at all about HTTP) would make it possible to also fully exploit OAuth's scopes and add a caching layer such as Squid/Varnish maintaining the possibility of purging when needed (that's not really doable when the URI schema is too relaxed). On Sat, Nov 10, 2012 at 6:46 PM, Bartosz Dziewoński &lt;matma.rex(a)gmail.com&gt;wrote;wrote: -- --- Federico "Lox" Lucignano Senior Lead Engineer - Mobile Team Wikia sp.z.o.o. email: federico(a)wikia-inc.com web: Lox-o-Drome <http://lox-o-drome.blogspot.com>

Interesting presentation at that link, Sumana; thanks for sharing. I wonder how the "17 RESTful design concepts" have been selected since I see some major ones missing, such as uniform interface which is quite more RESTful than just "use of HTTP methods": the MW API, using the HTTP protocol, is accepting POST/GET requests only, but not PUT or DELETE which are part of the uniform interface and rather prefers overloaded POST, and I tend to disagree on "HTTP method override" being a concept really adherent to REST (and that's not only me, there's plenty of literature on the topic supporting this point of view); also "addressability of the resources", another fundament, is missing and our API is not compliant there as well. I also don't recall "versioned endpoints" being part of any core concept of the REST interface, it seems to me that this deck of slides is a bit imprecise, I also find funny that on slide No. 4 the cover of "RESTful Web Services" by Richardson & Ruby is shown (and is also mentioned at point No. 14 in the references hosted on the page of the full paper) since if the author of this deck would have really recognized it as the "Design guidelines" (the way it is labeled on the deck), then the set of 17 concepts would have been quite different and the ratings of good part of the evaluated API's would have looked different as well. Overall it looks more like Renzel, as it is common practice when REST is involved, has rated some popular API's against his own understanding of "RESTful", something more near to REST-RPC hybrids. On Wed, Dec 5, 2012 at 12:59 AM, Sumana Harihareswara &lt;sumanah(a)wikimedia.org -- --- Federico "Lox" Lucignano Senior Lead Engineer - Mobile Team Wikia sp.z.o.o. email: federico(a)wikia-inc.com web: Lox-o-Drome <http://lox-o-drome.blogspot.com>