Proposed removal of some API output formats

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Proposed removal of some API output formats

Max Semenik
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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

Thomas Gries
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"



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

signature.asc (499 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

Chad
In reply to this post by Max Semenik
On Wed, Feb 8, 2012 at 2:31 PM, Max Semenik <[hidden email]> 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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

Svip
In reply to this post by Thomas Gries
On 8 February 2012 20:39, Thomas Gries <[hidden email]> 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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

Tim Starling-2
In reply to this post by Max Semenik
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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

MZMcBride-2
In reply to this post by Max Semenik
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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

Chad
On Wed, Feb 8, 2012 at 5:44 PM, MZMcBride <[hidden email]> 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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

Roan Kattouw-2
In reply to this post by Tim Starling-2
On Wed, Feb 8, 2012 at 11:42 PM, Tim Starling <[hidden email]> 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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Proposed removal of some API output formats

Diederik van Liere
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 <[hidden email]> wrote:

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

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