Page MenuHomePhabricator

API output for boolean values is unintuitive
Closed, ResolvedPublic

Description

The boolean values returned by the API isn't very intuitive for use:

For example, the subpages boolean.

For XML: http://en.wikipedia.org/w/api.php?action=query&meta=siteinfo&siprop=namespaces%7cnamespacealiases&format=xmlfm
For PHP: http://en.wikipedia.org/w/api.php?action=query&meta=siteinfo&siprop=namespaces%7cnamespacealiases&format=phpfm
Can be seen better in DBG: http://en.wikipedia.org/w/api.php?action=query&meta=siteinfo&siprop=namespaces%7cnamespacealiases&format=dbgfm
For JSON:
http://en.wikipedia.org/w/api.php?action=query&meta=siteinfo&siprop=namespaces%7cnamespacealiases&format=jsonfm
For YAML:
http://en.wikipedia.org/w/api.php?action=query&meta=siteinfo&siprop=namespaces%7cnamespacealiases&format=yamlfm
For WDDX:
http://en.wikipedia.org/w/api.php?action=query&meta=siteinfo&siprop=namespaces%7cnamespacealiases&format=wddxfm

For all of them boolean values are represented as a empty string rather than an intuitive boolean value.

For PHP and JS the best output would be true/false rather than a string you need to explicitly test for.
I don't know much about YAML.
As for WDDX, even just looking at the output it should be apparent that there should be a boolean type that the API should be outputting.
And even XML doesn't follow a proper standard, even if you go by the normal 'boolean' type use inside of (X)HTML for checkboxes and selects, the proper output should be subpages="subpages" for true.

In some languages it may even be possible for errors to come out of trying to use the data in a simple format if you don't add a bunch of unnecessary cruft to your code to explicitly test for the unintuitive output.


Version: unspecified
Severity: minor

Details

Reference
bz13299

Event Timeline

bzimport raised the priority of this task from to Lowest.Nov 21 2014, 10:04 PM
bzimport set Reference to bz13299.
bzimport added a subscriber: Unknown Object (MLST).

Bryan.TongMinh wrote:

I agree that the current standard for boolean items is fully unintuitive. Unfortunately changing this will cause massive breakage among anything that uses the API. Suggest WONTFIX.

Surely it should be possible to distinguish between subpages="" and no subpages attribute at all? The problem is (again) XML, which has no real boolean support. In hindsight, it sucks that we even chose to support it, considering all the special treatment it gets (such as the setIndexedTagName() function). Anyway, like Bryan said, we're not gonna change something that has been in the API from the beginning as that would break every single application that uses the API.

Hmmm, ya, that could be an issue...
However, it may still be possible to fix some of them.

Currently for XML we use:

  • and [subpages=""]

But the proper output would be:

  • and [subpages="subpages"]

So unless applications were specifically testing foo == "", then it shouldn't break.

But what about a sort of migration? Introduce some sort of compatibility parameter into the API.
The ones not using it, would get old output, and the ones using it would get newer output that they would expect.

It could either be done by some sort of &compatibility=1.5 where we mark certain types of breaking changes inside the API and someone can use the compatibility marker to make sure that the output will stay the same till they upgrade their app to use newer output.

Or, we could just focus on this one, and basically replace the format parameter or the format names, so &format= would output old formats, but a newer one &apiformat= perhaps would output newer format, so both new and old applications would be supported.

(In reply to comment #3)

It could either be done by some sort of &compatibility=1.5 where we mark
certain types of breaking changes inside the API and someone can use the
compatibility marker to make sure that the output will stay the same till they
upgrade their app to use newer output.

That was brought up at IRC some time ago, and I was wary of it because it'd mean keeping lots of old stuff around just because some guy is still using 1.0

Or, we could just focus on this one, and basically replace the format parameter
or the format names, so &format= would output old formats, but a newer one
&apiformat= perhaps would output newer format, so both new and old applications
would be supported.

We could change it, but I don't see whether it would be *necessary*: is this actually an issue for clients parsing XML output? "If it ain't broken, don't fix it."

robert wrote:

There is no "proper" way of outputting a boolean value in XML.

If the application knows that a boolean attribute may appear (such as the namespace list) then all it needs to do is identify whether the attribute appears at all (it doesn't matter whether it has content or not -- the fact it exists is good enough to indicate boolean true. For example in XHTML the attribute name is used to indicate boolean true in drop down boxes (<select value="1" selected>Name</select>).

In a simillar vien to arguing that 'selected=""' is unintuitive you could argue that 'selected="true"' is equally unintuitive as the later is effectively representing a string\integer value. Regardless I see little point in introducing a compatibility system for such a trivial issue. The current method is correct enough for anyone to identify how the system works (if you look on the namespace list it will be obvious that 'subpages=""' means that subpages are enabled and 'subpages="subpages"' is no more correct than the currrent output.

Legoktm changed the task status from Declined to Resolved.May 28 2015, 11:14 PM
Legoktm claimed this task.
Legoktm subscribed.
Legoktm set Security to None.