Hi, this idea had floated around for quite some time, but now that bug 34257[1] was added to the long list of problems, I would like to step up and start some progress. We[2] propose to remove the following formats[3]:
* WDDX - doesn't seem to be used by anyone. Doesn't look sane either. * YAML - we don't serve real YAML anyway, currently it's just a subset of JSON. * rawfm - was created for debugging the JSON formatter aeons ago, not useful for anything now. * txt, dbg, dump - the only reason they were added is that it was possible to add them, they don't serve the purpose of machine/machine communication.
So, only 3 formats would remain: * JSON - *the* recommended API format * XML - evil and clumsy but sadly used too widely to be revoved in the foreseeable future * php - this one is used by several extensions and probably by some third-party reusers, so we won't remove it this time. However, any new uses of it should be discouraged.
We plan to remove the aforementioned formats as soon as MediaWiki 1.19 is branched so that these changes will take effect in 1.20, but would like to hear from you first if there are good reasons why we shouldn't do it or postpone it. Please have your say.
------ [1] https://bugzilla.wikimedia.org/show_bug.cgi?id=34257 [2] Me and Roan Kattouw, one of API's primary developers [3] https://www.mediawiki.org/wiki/API:Data_formats
On 8 February 2012 20:39, Thomas Gries mail@tgries.de wrote:
Am 08.02.2012 20:31, schrieb Max Semenik:
- txt, dbg, dump - the only reason they were added is that it was
possible to add them, they don't serve the purpose of machine/machine communication.
I think we should keep "txt" or "raw"
That's an excellent reasoning for why we should keep "txt" or "raw". Do you use either?
On Wed, Feb 8, 2012 at 2:31 PM, Max Semenik maxsem.wiki@gmail.com wrote:
We plan to remove the aforementioned formats as soon as MediaWiki 1.19 is branched so that these changes will take effect in 1.20, but would like to hear from you first if there are good reasons why we shouldn't do it or postpone it. Please have your say.
For a stable API, that's far too fast of a deprecation path. We don't even remove core functions that fast (or shouldn't). I'd suggest throwing some kinds of warnings in the output for at least one release (1.20) and then target them for removal in 1.21.
-Chad
On 09/02/12 06:31, Max Semenik wrote:
Hi, this idea had floated around for quite some time, but now that bug 34257[1] was added to the long list of problems, I would like to step up and start some progress.
What are the other problems?
- YAML - we don't serve real YAML anyway, currently it's just a subset of JSON.
YAML is just a few harmless lines of code, why would you want to remove it?
-- Tim Starling
On Wed, Feb 8, 2012 at 11:42 PM, Tim Starling tstarling@wikimedia.org wrote:
What are the other problems?
I'm not sure what Max is referring to, other than the fact that I hate XML (or at least using XML for this API) and generally don't like the fact that we have to support so many formats. As I said on Bugzilla earlier today, if I ever were to rewrite the API from scratch it'd be JSON-only. However, we can't actually get rid of XML realistically.
- YAML - we don't serve real YAML anyway, currently it's just a subset
of JSON.
YAML is just a few harmless lines of code, why would you want to remove it?
Yeah that can probably stay, it's not worth breaking anything over.
Roan
Hi,
Andre Engels did some analysis of the type of API formats used. The data is from a single random Sunday in late 2011:
1997267 application/json 314285 text/xml 171259 - 68358 application/vnd.php.serialized 55549 text/html 34680 text/javascript 8907 application/x-www-form-urlencoded 8882 application/xml 807 application/rsd+xml 467 text/text 105 application/x-www-form-urlencoded; 18 application/yaml 1 multipart/form-data;
yaml is used for the query and parse API actions. On this particular day, the following services used yaml:
http://www.huddba.cz corporama.com reftag.appspot.com
Thank you Andre!
Best, Diederik
On Wed, Feb 8, 2012 at 7:45 PM, Roan Kattouw roan.kattouw@gmail.com wrote:
On Wed, Feb 8, 2012 at 11:42 PM, Tim Starling tstarling@wikimedia.org wrote:
What are the other problems?
I'm not sure what Max is referring to, other than the fact that I hate XML (or at least using XML for this API) and generally don't like the fact that we have to support so many formats. As I said on Bugzilla earlier today, if I ever were to rewrite the API from scratch it'd be JSON-only. However, we can't actually get rid of XML realistically.
- YAML - we don't serve real YAML anyway, currently it's just a subset
of JSON.
YAML is just a few harmless lines of code, why would you want to remove it?
Yeah that can probably stay, it's not worth breaking anything over.
Roan
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Max Semenik wrote:
We plan to remove the aforementioned formats as soon as MediaWiki 1.19 is branched so that these changes will take effect in 1.20, but would like to hear from you first if there are good reasons why we shouldn't do it or postpone it. Please have your say.
Breaking changes in the API are a Bad Thing. Sometimes Bad Things must be done, but before doing so, I'd like to see the other options exhausted.
Has there been any discussion of the costs/benefits of versioning the API, for example?
MZMcBride
On Wed, Feb 8, 2012 at 5:44 PM, MZMcBride z@mzmcbride.com wrote:
Max Semenik wrote:
We plan to remove the aforementioned formats as soon as MediaWiki 1.19 is branched so that these changes will take effect in 1.20, but would like to hear from you first if there are good reasons why we shouldn't do it or postpone it. Please have your say.
Breaking changes in the API are a Bad Thing. Sometimes Bad Things must be done, but before doing so, I'd like to see the other options exhausted.
Yeah I'm definitely +1 here. I'm fine with making breaking changes iff they're necessary but we should be as gentle as possible about it when they happen.
-Chad
wikitech-l@lists.wikimedia.org