A few weeks ago, a few Wikia and Wikimedia people started talking about rewriting MediaWiki's web API for greater flexibility, usability, and standardization. Notes from that meeting: https://www.mediawiki.org/wiki/API/API_rewrite/Kickoff_meeting
Federico Lucignano is one of the main developers on this effort. He will be doing API stuff for Wikia for the next 5 months. Wikia wants to attract motivated app developers and companies using Wikia's products to use the API. They also want to make the APIs more standards-compliant (a RESTful interface, using HTTP verbs), but that's a high-level goal. Mobile-related work is first, driving the direction of some of Federico's work, but this redesign would improve the whole platform, including the enterprise.
Wikimedia and Wikia want to work together on this. Wikimedia Foundation also wants to avoid boxing ourselves into special-purpose, specific apps. Right now we're in the very early stages and I believe Wikia's going to put out an RFC -- the initial research we discussed during the kickoff meeting is starting this week.
Some people have also begun talking about this issue on the bug " Make MediaWiki more RESTful": https://bugzilla.wikimedia.org/show_bug.cgi?id=41837 in case you want to check that out.
Welcome, Federico!
Thanks Sumana.
Please, let me also introduce two other members of Wikia's team that will contribute to this first step: Jakub Olek and Owen Davis.
We're very excited for this opportunity to work together with the Foundation and the community revolving around it!
On Wed, Nov 7, 2012 at 12:42 AM, Sumana Harihareswara <sumanah@wikimedia.org
wrote:
A few weeks ago, a few Wikia and Wikimedia people started talking about rewriting MediaWiki's web API for greater flexibility, usability, and standardization. Notes from that meeting: https://www.mediawiki.org/wiki/API/API_rewrite/Kickoff_meeting
Federico Lucignano is one of the main developers on this effort. He will be doing API stuff for Wikia for the next 5 months. Wikia wants to attract motivated app developers and companies using Wikia's products to use the API. They also want to make the APIs more standards-compliant (a RESTful interface, using HTTP verbs), but that's a high-level goal. Mobile-related work is first, driving the direction of some of Federico's work, but this redesign would improve the whole platform, including the enterprise.
Wikimedia and Wikia want to work together on this. Wikimedia Foundation also wants to avoid boxing ourselves into special-purpose, specific apps. Right now we're in the very early stages and I believe Wikia's going to put out an RFC -- the initial research we discussed during the kickoff meeting is starting this week.
Some people have also begun talking about this issue on the bug " Make MediaWiki more RESTful": https://bugzilla.wikimedia.org/show_bug.cgi?id=41837 in case you want to check that out.
Welcome, Federico!
Sumana Harihareswara Engineering Community Manager Wikimedia Foundation
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
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@wikia-inc.com wrote:
Thanks Sumana.
Please, let me also introduce two other members of Wikia's team that will contribute to this first step: Jakub Olek and Owen Davis.
We're very excited for this opportunity to work together with the Foundation and the community revolving around it!
On Wed, Nov 7, 2012 at 12:42 AM, Sumana Harihareswara sumanah@wikimedia.org wrote: A few weeks ago, a few Wikia and Wikimedia people started talking about rewriting MediaWiki's web API for greater flexibility, usability, and standardization. Notes from that meeting: https://www.mediawiki.org/wiki/API/API_rewrite/Kickoff_meeting
Federico Lucignano is one of the main developers on this effort. He will be doing API stuff for Wikia for the next 5 months. Wikia wants to attract motivated app developers and companies using Wikia's products to use the API. They also want to make the APIs more standards-compliant (a RESTful interface, using HTTP verbs), but that's a high-level goal. Mobile-related work is first, driving the direction of some of Federico's work, but this redesign would improve the whole platform, including the enterprise.
Wikimedia and Wikia want to work together on this. Wikimedia Foundation also wants to avoid boxing ourselves into special-purpose, specific apps. Right now we're in the very early stages and I believe Wikia's going to put out an RFC -- the initial research we discussed during the kickoff meeting is starting this week.
Some people have also begun talking about this issue on the bug " Make MediaWiki more RESTful": https://bugzilla.wikimedia.org/show_bug.cgi?id=41837 in case you want to check that out.
Welcome, Federico!
Sumana Harihareswara Engineering Community Manager Wikimedia Foundation
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
--
Federico "Lox" Lucignano
Senior Lead Engineer - Mobile Team Wikia sp.z.o.o.
email: federico@wikia-inc.com web: Lox-o-Drome
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
On Thu, Nov 8, 2012 at 10:00 AM, NetizenApps netizenapps@gmail.com wrote:
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.
Assuming we did it like last time (when query.php was replaced with api.php), we would allow the two APIs to co-exist for a period of time, but with a declared end of life for the old interface.
Although considering that the number of people using api.php is many factors more than were ever using query.php--the sunset period should be much much longer this time.
-Chad
On 08/11/12 16:17, Chad wrote:
Assuming we did it like last time (when query.php was replaced with api.php), we would allow the two APIs to co-exist for a period of time, but with a declared end of life for the old interface.
Although considering that the number of people using api.php is many factors more than were ever using query.php--the sunset period should be much much longer this time.
-Chad
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!
On Thu, Nov 8, 2012 at 10:59 AM, Platonides platonides@gmail.com wrote:
On 08/11/12 16:17, Chad wrote:
Assuming we did it like last time (when query.php was replaced with api.php), we would allow the two APIs to co-exist for a period of time, but with a declared end of life for the old interface.
Although considering that the number of people using api.php is many factors more than were ever using query.php--the sunset period should be much much longer this time.
-Chad
I don't think it would be wise to remove the current api.
I don't either, I was just responding hypothetically.
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.
Indeed--there's no harm in trying new things.
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.
This is very important--we're not the only consumers of our own API. We've got hundreds (thousands?) of other consumers as well--all of whom should be considered.
Trashing existing documentation, people knowledge and libraries in exchange of a cool concept is a big no-no.
This is the most important point. We could make the coolest API on earth--but what good is it if we've caused developers tons of man-hours fixing their scripts (for no real gain on their end)
Long live the existing api!
+10
-Chad
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@gmail.com wrote:
On Thu, Nov 8, 2012 at 10:59 AM, Platonides platonides@gmail.com wrote:
On 08/11/12 16:17, Chad wrote:
Assuming we did it like last time (when query.php was replaced with
api.php),
we would allow the two APIs to co-exist for a period of time, but with a declared end of life for the old interface.
Although considering that the number of people using api.php is many
factors
more than were ever using query.php--the sunset period should be much
much
longer this time.
-Chad
I don't think it would be wise to remove the current api.
I don't either, I was just responding hypothetically.
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.
Indeed--there's no harm in trying new things.
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.
This is very important--we're not the only consumers of our own API. We've got hundreds (thousands?) of other consumers as well--all of whom should be considered.
Trashing existing documentation, people knowledge and libraries in exchange of a cool concept is a big no-no.
This is the most important point. We could make the coolest API on earth--but what good is it if we've caused developers tons of man-hours fixing their scripts (for no real gain on their end)
Long live the existing api!
+10
-Chad
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Huge +1 for long term backwards compatibility.
I can't quite see what problems this is trying to solve?
Reading through https://www.mediawiki.org/wiki/API/API_rewrite/Kickoff_meeting I don't see any argument for why we are moving to replace the current API. It reads more like "oh, this'll be cool"!
That said, I'm all for making Mediawiki more accessible to "apps"/mobile/whatever. In particular I'm thinking of o-auth (or similar), which is long overdue. Something like that would be very helpful for toolserver tools.
I'm just a bit confused about why we need a new api. What are we trying to fix? What are the goals? And most importantly, we need a clear idea of where the current API fails.
-- Chris
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@gmail.comwrote:
Huge +1 for long term backwards compatibility.
I can't quite see what problems this is trying to solve?
Reading through https://www.mediawiki.org/wiki/API/API_rewrite/Kickoff_meeting I don't see any argument for why we are moving to replace the current API. It reads more like "oh, this'll be cool"!
That said, I'm all for making Mediawiki more accessible to "apps"/mobile/whatever. In particular I'm thinking of o-auth (or similar), which is long overdue. Something like that would be very helpful for toolserver tools.
I'm just a bit confused about why we need a new api. What are we trying to fix? What are the goals? And most importantly, we need a clear idea of where the current API fails.
-- Chris
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
On Thu, Nov 8, 2012 at 11:29 PM, Nicolas Vervelle nvervelle@gmail.com wrote:
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.
Seconded. My day job involves, among other things, software development for MacOS, and at times it feels like the Red Queen's race: I need to run as fast as I can chasing the latest API shift just to keep the software in the same place. (For the historically inclined, Toolbox to CarbonLib to Carbon Framework to Intel Mac to Cocoa, with a potential mandatory shift to ARM in the future.)
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_though...), 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 carnildo@gmail.com wrote:
On Thu, Nov 8, 2012 at 11:29 PM, Nicolas Vervelle nvervelle@gmail.com wrote:
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.
Seconded. My day job involves, among other things, software development for MacOS, and at times it feels like the Red Queen's race: I need to run as fast as I can chasing the latest API shift just to keep the software in the same place. (For the historically inclined, Toolbox to CarbonLib to Carbon Framework to Intel Mac to Cocoa, with a potential mandatory shift to ARM in the future.)
-- Mark Wagner
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
On 10/11/12 03:44, Federico "Lox" Lucignano wrote:
stability (versioning, i.e. no more mass transitions),
This is really asking for a reference to xkcd 927 :)
Note that no matter how you versionate the api (heh, we could easily add a version parameter to the current one, too) if for some reason (eg. a new HTML5 feature allows to bypass one of the checks of the current api) it needs to be changed, we *will* break backwards compatibility.
It is uncommon that it happens, but we have been there, and the same situation may arise in the future, too. In the past we managed to keep BC quite well, though.
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 platonides@gmail.com wrote:
On 10/11/12 03:44, Federico "Lox" Lucignano wrote:
stability (versioning, i.e. no more mass transitions),
This is really asking for a reference to xkcd 927 :)
Note that no matter how you versionate the api (heh, we could easily add a version parameter to the current one, too) if for some reason (eg. a new HTML5 feature allows to bypass one of the checks of the current api) it needs to be changed, we *will* break backwards compatibility.
It is uncommon that it happens, but we have been there, and the same situation may arise in the future, too. In the past we managed to keep BC quite well, though.
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
2012/11/10 Federico "Lox" Lucignano federico@wikia-inc.com:
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.
You could also add a "api" URL parameter to the current API that would default to "v1", and possibly accept other values like "v2" for new versions. ("version" parameter is already taken; I think we could live with it.)
No need to change the entire URL format.
-- Matma Rex
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 matma.rex@gmail.comwrote:
2012/11/10 Federico "Lox" Lucignano federico@wikia-inc.com:
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.
You could also add a "api" URL parameter to the current API that would default to "v1", and possibly accept other values like "v2" for new versions. ("version" parameter is already taken; I think we could live with it.)
No need to change the entire URL format.
-- Matma Rex
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
On 11/10/2012 10:23 AM, Federico "Lox" Lucignano wrote:
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).
Just wanted to share the latest status on this from Wikia: https://www.mediawiki.org/wiki/API/REST_proposal/status
"* Finishing evaluating ROA as the underlying REST architecture for the RFC * Defined the possible format for scope-defining parameters (both hierarchical and single-level) * Started identifying the core set of resources to be exposed via the REST interface, evaluating overloaded Post as a way to allow for 3rd party extensions to a resource * Completed the outline for a first revision of a protocol-agnostic router/dispatcher model along with the core set of classes of the API framework
Next step: finalize the first set of docs and move the discussion to a larger group including API designer and Tech leads."
On a completely separate note: I just saw that http://www.slideshare.net/DominikRenzel/todays-top-restful-services-and-why-... on page 6 grades MediaWiki and other popular applications/services on how RESTful they are.
I'm assuming that red/pink/light green/dark green correlates to "noncompliant/not very compliant/kinda compliant/compliant".
Red: Formal Description Links in Representations Forms in Representations Resource Types Versioned Endpoint Format Selection
Pink: Parameter Sources
Light green: HTTP Method Override
Dark green: Scoping Information Meaningful HTTP Status Use of HTTP Methods
http://www.springerlink.com/index/42307200X642M240.pdf has the full paper in case people want to look at that.
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 <sumanah@wikimedia.org
wrote:
On 11/10/2012 10:23 AM, Federico "Lox" Lucignano wrote:
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).
Just wanted to share the latest status on this from Wikia: https://www.mediawiki.org/wiki/API/REST_proposal/status
"* Finishing evaluating ROA as the underlying REST architecture for the RFC
- Defined the possible format for scope-defining parameters (both
hierarchical and single-level)
- Started identifying the core set of resources to be exposed via the
REST interface, evaluating overloaded Post as a way to allow for 3rd party extensions to a resource
- Completed the outline for a first revision of a protocol-agnostic
router/dispatcher model along with the core set of classes of the API framework
Next step: finalize the first set of docs and move the discussion to a larger group including API designer and Tech leads."
On a completely separate note: I just saw that
http://www.slideshare.net/DominikRenzel/todays-top-restful-services-and-why-... on page 6 grades MediaWiki and other popular applications/services on how RESTful they are.
I'm assuming that red/pink/light green/dark green correlates to "noncompliant/not very compliant/kinda compliant/compliant".
Red: Formal Description Links in Representations Forms in Representations Resource Types Versioned Endpoint Format Selection
Pink: Parameter Sources
Light green: HTTP Method Override
Dark green: Scoping Information Meaningful HTTP Status Use of HTTP Methods
http://www.springerlink.com/index/42307200X642M240.pdf has the full paper in case people want to look at that.
-- Sumana Harihareswara Engineering Community Manager Wikimedia Foundation
Will there be any effort made to improve the situation with wiki text and formatting? The biggest problem I have isn't the API specifically (which works fine for my needs), but the fact that it is near impossible to implement WYSIWYG editing of wiki text. Also the lack of consistency between display of subject areas and pages in general make display formatting very difficult.
It would be great if the new API ( or even just addition to the existing API) could return structured XML for the entire page, and also take the XML as input for page changes.
Also I should add that API versioning is a maintenance nightmare without unit tests and and an API test team, and the deployment strategy for new versions into production for Wikipedia seems sort of cavalier at the moment. I am basing this statement off the idea that versioning means you want to have the flexibility to make large scale changes without braking older clients.
Anyway I am not opposed to some sort of REST extensions for certain queries that make sense (i.e., lists of categories to which a page belongs), but it seems like you want to start over from scratch when these additions could just be added into the current API. Just provide something in the query that allows us to get a context id that we can pass back in future transactions. Then client apps can adopt RESTful queries where they need it, especially since requiring stateful queries increases the learning curve for API usage.
Robert
On Tue, Nov 6, 2012 at 6:42 PM, Sumana Harihareswara sumanah@wikimedia.org wrote:
Some people have also begun talking about this issue on the bug " Make MediaWiki more RESTful": https://bugzilla.wikimedia.org/show_bug.cgi?id=41837 in case you want to check that out.
I think this is the worst idea outlined on that kickoff page. I think Brian's comment sums it up perfectly for me: "not a fan of restful stuff in general, usually seems to be a solution in search of a problem" [0]. Adding more functionality to the API is great, and having OAuth (or something similar) would be fantastic--I'm really not convinced we need to to Completely Rewrite(tm) the API to accomplish this.
-Chad
[0] https://bugzilla.wikimedia.org/show_bug.cgi?id=41837#c15
mediawiki-api@lists.wikimedia.org