It's almost New Year, and time for presents (according to the Russian traditions).
I hereby present you the API versioning framework. Navigate to https://gerrit.wikimedia.org/r/#/c/41014/ and get that patch to your local installation for a test run.
There shouldn't be any visible functionality changes. At least that was the goal. But now we can easily add a new version module or a submodule (prop/list/etc) without breaking existing code.
To see it in action -- in ApiMain.php, add this line into $Modules array: 'query2' => 'ApiQuery',
it adds another version of query implemented by the same existing class.
now if you look at http://localhost/api.php you will see
* action=query * This module is obsolete. See old documentation at api.php?action=help&modules=query * action=query2 * ... -- the regular query parameters -- ...
both query and query2 will work identically in this example unless you change ApiQuery.php.
Let the rotten egg throwing commence!
Once we settle on this, I propose you join me at the mediawiki labs -- https://labsconsole.wikimedia.org/wiki/Nova_Resource:Mediawiki-api to develop and test the actual changes to the APIv2 interface. To keep it going full steam ahead, I will accept ideas, criticisms, cookies, code patches, small unmarked bills and large paychecks, but most importantly - your time analyzing and commenting this effort.
--Yurik
On Fri, Dec 28, 2012 at 5:45 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Let the rotten egg throwing commence!
Sorry to be dense, but where is a good place to learn about what changes are in being planned for v2 of the API?
//Ed
Bugzilla, mailing list archives, our heads. Now that versionning is per-module, we can start revising them one at a time to support new capabilities. Bugzilla has 150+ open API bugs.
There is an API v2 tracking bug at https://bugzilla.wikimedia.org/show_bug.cgi?id=38891 Make sure bug 38891 depends on any v2 requests you add.
All open API bugs: https://bugzilla.wikimedia.org/buglist.cgi?order=Importance&query_format...
Or we could create an RFC at http://www.mediawiki.org/wiki/RFC
On Fri, Dec 28, 2012 at 5:54 AM, Ed Summers ehs@pobox.com wrote:
On Fri, Dec 28, 2012 at 5:45 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Let the rotten egg throwing commence!
Sorry to be dense, but where is a good place to learn about what changes are in being planned for v2 of the API?
//Ed
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Thanks for the additional details :-)
Perhaps this isn't important right now, but have you given any thought to the naming of the version? I kind of like the clarity and goals of the semver system [1]. The reason why I bring this up is that fixing existing bugs with the API sounds like minor change in the version number, whereas a major change from (v1 -> v2) implies a break with backwards compatibility to create a new API. Perhaps framing the work in terms of semver will help organize the work?
By the way, I quite like the sound of a modern looking (aka RESTful) API for MediaWiki. Does that fit how you are thinking about v2 of the API?
//Ed
On Fri, Dec 28, 2012 at 6:10 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Bugzilla, mailing list archives, our heads. Now that versionning is per-module, we can start revising them one at a time to support new capabilities. Bugzilla has 150+ open API bugs.
There is an API v2 tracking bug at https://bugzilla.wikimedia.org/show_bug.cgi?id=38891 Make sure bug 38891 depends on any v2 requests you add.
All open API bugs: https://bugzilla.wikimedia.org/buglist.cgi?order=Importance&query_format...
Or we could create an RFC at http://www.mediawiki.org/wiki/RFC
On Fri, Dec 28, 2012 at 5:54 AM, Ed Summers ehs@pobox.com wrote:
On Fri, Dec 28, 2012 at 5:45 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Let the rotten egg throwing commence!
Sorry to be dense, but where is a good place to learn about what changes are in being planned for v2 of the API?
//Ed
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
I'm not sure how semver applies here really - every number change (1->2) is a breaking change, and v2 could be marked as experimental in the docs until it is ready.
Not sure about restful yet - it might not provide much benefit to the users. I guess we should have either a different thread or bug reports discussing proposed structure change.
On Fri, Dec 28, 2012 at 6:20 AM, Ed Summers ehs@pobox.com wrote:
Thanks for the additional details :-)
Perhaps this isn't important right now, but have you given any thought to the naming of the version? I kind of like the clarity and goals of the semver system [1]. The reason why I bring this up is that fixing existing bugs with the API sounds like minor change in the version number, whereas a major change from (v1 -> v2) implies a break with backwards compatibility to create a new API. Perhaps framing the work in terms of semver will help organize the work?
By the way, I quite like the sound of a modern looking (aka RESTful) API for MediaWiki. Does that fit how you are thinking about v2 of the API?
//Ed
On Fri, Dec 28, 2012 at 6:10 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Bugzilla, mailing list archives, our heads. Now that versionning is per-module, we can start revising them one at a time to support new capabilities. Bugzilla has 150+ open API bugs.
There is an API v2 tracking bug at https://bugzilla.wikimedia.org/show_bug.cgi?id=38891 Make sure bug 38891 depends on any v2 requests you add.
All open API bugs:
https://bugzilla.wikimedia.org/buglist.cgi?order=Importance&query_format...
Or we could create an RFC at http://www.mediawiki.org/wiki/RFC
On Fri, Dec 28, 2012 at 5:54 AM, Ed Summers ehs@pobox.com wrote:
On Fri, Dec 28, 2012 at 5:45 AM, Yuri Astrakhan <
yuriastrakhan@gmail.com>
wrote:
Let the rotten egg throwing commence!
Sorry to be dense, but where is a good place to learn about what changes are in being planned for v2 of the API?
//Ed
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
On Fri, Dec 28, 2012 at 6:28 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
I'm not sure how semver applies here really - every number change (1->2) is a breaking change, and v2 could be marked as experimental in the docs until it is ready.
Ok, so you are seeing every increment as a major version change then. I think semver helps to be explicit about what the version number actually means. I guess in part I'm trying to understand why fixing bugs involves a major version change, and breaking backwards compatibility.
Not sure about restful yet - it might not provide much benefit to the users. I guess we should have either a different thread or bug reports discussing proposed structure change.
Mark Nottingham recently wrote about semver, REST and how to evolve Web APIs [1]. I think developers are increasingly familiar with interacting with REST style APIs (Amazon S3, Twitter, Facebook, etc). In general REST APIs encourage simpler documentation, easier cacheability, and can often make the need for 3rd party API libraries disappear, if a good HTTP library is available.
A change to the major version of the Mediawiki API might be a good time to think make a fresh start and think about the API in this way...or not :-)
//Ed
Ok, so you are seeing every increment as a major version change then. I think semver helps to be explicit about what the version number actually means. I guess in part I'm trying to understand why fixing bugs involves a major version change, and breaking backwards compatibility.
version here is not for notification, its for the client to specify what
it expects the behavior to be. Fixing bugs does not change version, not unless there is a *breaking* change - if we decide to obsolete ver5 and start ver6 due to inability to include new features. This is a very rare occurrence. APIv1 lasted for 6 years and still going strong :)
Mark Nottingham recently wrote about semver, REST and how to evolve Web APIs [1]. I think developers are increasingly familiar with interacting with REST style APIs (Amazon S3, Twitter, Facebook, etc). In general REST APIs encourage simpler documentation, easier cacheability, and can often make the need for 3rd party API libraries disappear, if a good HTTP library is available.
A change to the major version of the Mediawiki API might be a good time to think make a fresh start and think about the API in this way...or not :-)
Make a proposal, we discuss, and than we start throwing rotten tomatoes in
a different direction ;)
Following some good feedback, I have created an RFC page detailing many changes to the new API.
Please add your suggestions and requests there.
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future
On Mon, Jan 7, 2013 at 9:20 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Following some good feedback, I have created an RFC page detailing many changes to the new API.
Please add your suggestions and requests there.
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future
That page doesn't seem to be laid out very well for discussing your proposals. How do you intend that to work?
I went through the proposal and despite I technically understand how that would look like, I'd suggest to add a section with a real example of how the PHP code of one module supporting 2/3 versions of the same action would look like.
It would help assessing the maintainability of the proposed model.
Thanks.
On Mon, Jan 7, 2013 at 8:43 PM, Brad Jorsch bjorsch@wikimedia.org wrote:
On Mon, Jan 7, 2013 at 9:20 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Following some good feedback, I have created an RFC page detailing many changes to the new API.
Please add your suggestions and requests there.
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future
That page doesn't seem to be laid out very well for discussing your proposals. How do you intend that to work?
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Federico, I have added some PHP samples, is this what you were looking for?
Also, added to the page - query~2 submodule (list, prop, meta) versioning and behavior.
https://www.mediawiki.org/wiki/Requests_for_comment/API_Future
P.S. This is wiki, feel free to comment and/or change the proposal.
On Mon, Jan 7, 2013 at 3:24 PM, Federico "Lox" Lucignano < federico@wikia-inc.com> wrote:
I went through the proposal and despite I technically understand how that would look like, I'd suggest to add a section with a real example of how the PHP code of one module supporting 2/3 versions of the same action would look like.
It would help assessing the maintainability of the proposed model.
Thanks.
On Mon, Jan 7, 2013 at 8:43 PM, Brad Jorsch bjorsch@wikimedia.org wrote:
On Mon, Jan 7, 2013 at 9:20 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Following some good feedback, I have created an RFC page detailing many changes to the new API.
Please add your suggestions and requests there.
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future
That page doesn't seem to be laid out very well for discussing your proposals. How do you intend that to work?
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 http://lox-o-drome.blogspot.com
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Thanks Yuri.
I'll give further feedback on the talk page.
On Tue, Jan 8, 2013 at 10:19 AM, Yuri Astrakhan yuriastrakhan@gmail.comwrote:
Federico, I have added some PHP samples, is this what you were looking for?
Also, added to the page - query~2 submodule (list, prop, meta) versioning and behavior.
https://www.mediawiki.org/wiki/Requests_for_comment/API_Future
P.S. This is wiki, feel free to comment and/or change the proposal.
On Mon, Jan 7, 2013 at 3:24 PM, Federico "Lox" Lucignano < federico@wikia-inc.com> wrote:
I went through the proposal and despite I technically understand how that would look like, I'd suggest to add a section with a real example of how the PHP code of one module supporting 2/3 versions of the same action would look like.
It would help assessing the maintainability of the proposed model.
Thanks.
On Mon, Jan 7, 2013 at 8:43 PM, Brad Jorsch bjorsch@wikimedia.orgwrote:
On Mon, Jan 7, 2013 at 9:20 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Following some good feedback, I have created an RFC page detailing many changes to the new API.
Please add your suggestions and requests there.
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future
That page doesn't seem to be laid out very well for discussing your proposals. How do you intend that to work?
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 http://lox-o-drome.blogspot.com
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
I think we should discuss it on the talk page, as liquid threads are on and running nicely. If someone has a sub-proposal, it should be added as a section to the main page with examples, or if its big, as a subpage. When we have the points of contention, we could have a yei/nei voting underneath each, but i think this is a bit premature until the overall discussion on the talk page takes place.
On Mon, Jan 7, 2013 at 2:43 PM, Brad Jorsch bjorsch@wikimedia.org wrote:
On Mon, Jan 7, 2013 at 9:20 AM, Yuri Astrakhan yuriastrakhan@gmail.com wrote:
Following some good feedback, I have created an RFC page detailing many changes to the new API.
Please add your suggestions and requests there.
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future
That page doesn't seem to be laid out very well for discussing your proposals. How do you intend that to work?
Mediawiki-api mailing list Mediawiki-api@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-api
mediawiki-api@lists.wikimedia.org