Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Wikipedia: Wikitech

Proposed removal of some API output formats

 

 

Wikipedia wikitech RSS feed   Index | Next | Previous | View Threaded


maxsem.wiki at gmail

Feb 8, 2012, 11:31 AM

Post #1 of 11 (492 views)
Permalink
Proposed removal of some API output formats

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

--
Best regards,
Max Semenik ([[User:MaxSem]])


_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


mail at tgries

Feb 8, 2012, 11:39 AM

Post #2 of 11 (485 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

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"
Attachments: signature.asc (0.48 KB)


innocentkiller at gmail

Feb 8, 2012, 12:48 PM

Post #3 of 11 (483 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

On Wed, Feb 8, 2012 at 2:31 PM, Max Semenik <maxsem.wiki [at] gmail> 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

_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


svippy at gmail

Feb 8, 2012, 1:18 PM

Post #4 of 11 (480 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

On 8 February 2012 20:39, Thomas Gries <mail [at] tgries> 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?

_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


tstarling at wikimedia

Feb 8, 2012, 2:42 PM

Post #5 of 11 (486 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

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


_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


z at mzmcbride

Feb 8, 2012, 2:44 PM

Post #6 of 11 (480 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

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



_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


innocentkiller at gmail

Feb 8, 2012, 3:01 PM

Post #7 of 11 (480 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

On Wed, Feb 8, 2012 at 5:44 PM, MZMcBride <z [at] mzmcbride> 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 mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


bawolff+wn at gmail

Feb 8, 2012, 3:01 PM

Post #8 of 11 (484 views)
Permalink
Proposed removal of some API output formats [In reply to]

> Message: 5
> Date: Wed, 8 Feb 2012 23:31:37 +0400
> From: Max Semenik <maxsem.wiki [at] gmail>
> To: MediaWiki API announcements & discussion
> † † † <mediawiki-api [at] lists>, † †Wikimedia developers
> † † † <wikitech-l [at] lists>
> Subject: [Wikitech-l] Proposed removal of some API output formats
> Message-ID: <568811305.20120208233137 [at] gmail>
> Content-Type: text/plain; charset=utf-8
>
> 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
>
> --
> Best regards,
> Max Semenik ([[User:MaxSem]])
>


I have scripts that use the txt format. (Things that were originally
super hacky shell scripts, that became more permanently run scripts
[but still hacky beyond belief]). txt is mostly easy to process with
grep (So was the older version of yaml formatting). However, hopefully
not too many people were stupid enough to try to parse the api output
using grep. (In case anyone is wondering if using shell scripts to
access the api is really as bad as it sounds, I assure you its even
worse than you think).

If json becomes the new recommended format, does that mean that not
passing a format parameter would result in jsonfm instead of xmlfm?
(Probably not since the jsonfm pretty printer isn't all that pretty at
the moment).

> 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

+1.

--
-bawolff

_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


roan.kattouw at gmail

Feb 8, 2012, 4:32 PM

Post #9 of 11 (480 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

On Thu, Feb 9, 2012 at 12:01 AM, bawolff <bawolff+wn [at] gmail> wrote:
> If json becomes the new recommended format, does that mean that not
> passing a format parameter would result in jsonfm instead of xmlfm?
> (Probably not since the jsonfm pretty printer isn't all that pretty at
> the moment).
>
One major problem is that in JSON, newlines are required to be
represented with \n . That means it's impossible to produce a legible
help page in valid JSON, so I think we should stick with xmlfm.

Roan

_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


roan.kattouw at gmail

Feb 8, 2012, 4:45 PM

Post #10 of 11 (474 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

On Wed, Feb 8, 2012 at 11:42 PM, Tim Starling <tstarling [at] wikimedia> 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 [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l


dvanliere at gmail

Feb 9, 2012, 7:42 AM

Post #11 of 11 (469 views)
Permalink
Re: Proposed removal of some API output formats [In reply to]

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 [at] gmail> wrote:
>
> On Wed, Feb 8, 2012 at 11:42 PM, Tim Starling <tstarling [at] wikimedia> 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 [at] lists
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l

_______________________________________________
Wikitech-l mailing list
Wikitech-l [at] lists
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

Wikipedia wikitech RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.