[
https://issues.apache.org/jira/browse/CONNECTORS-99?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13400069#comment-13400069
]
Adrian Conlon commented on CONNECTORS-99:
-----------------------------------------
I do understand why from one point of view this might be seen as a wish item to
make the API more consistent with regards JSON usage, but I think it could also
be seen more seriously as an API documentation bug (as Andrzej points out).
Perhaps where the documentation currently talks of returning a JSON array where
lists are concerned, this could point to a generalised section which talks (a
little) about why singular and null data are handled differently.
For example:
Where the listing of all output connections results currently reads:
{"outputconnection":[<list_of_output_connection_objects>]} OR
{"error":<error_text>}
perhaps it could read:
An "outputconnection" keyed list OR {"error":<error_text>}
and the general sections on lists, could read:
Lists can be returned as either a keyed JSON array, when the number of
items returned is
greater than one, a single unkeyed JSON item when only one value is
returned or a null JSON
object where the returned list is logically empty.
(As a personal aside, I've just spent a day or so tracking down problems in my
usage of the ManifoldCF API related to this issue! A little extra
documentation in this area would definitely have been useful.)
> REST API serialization inconsistency
> ------------------------------------
>
> Key: CONNECTORS-99
> URL: https://issues.apache.org/jira/browse/CONNECTORS-99
> Project: ManifoldCF
> Issue Type: Wish
> Components: API
> Affects Versions: ManifoldCF 0.1, ManifoldCF 0.2, ManifoldCF 0.3
> Environment: ACF trunk.
> Reporter: Andrzej Bialecki
> Priority: Minor
> Fix For: ManifoldCF next
>
>
> There is some inconsistency in REST APIs that makes the returned values more
> difficult to process than necessary. It boils down to the fact that lists of
> values are serialized into JSON arrays only when there is more than 1 element
> on the list, but they are serialized into plain JSON objects when there is 0
> or 1 element on the list. Example:
> * listings of jobs, connectors, connections, repositories etc. all suffer
> from this symptom:
> {code}
> * 1 element:
> {"job":{"id":"1283811504796","description":"job 1" ...
> * 2 elements:
> {"job":[{"id":"1283811504796","description":"job 1" ...
> {code}
> * nested elements, such as e.g. job metadata:
> {code}
> 1 element:
>
> "metadata":{"_value_":"","_attribute_name":"jobKey1","_attribute_value":"jobVal1"}
> 2 elements:
>
> "metadata":[{"_value_":"","_attribute_name":"jobKey1","_attribute_value":"jobVal1"},{"_value_":"","_attribute_name":"jobKey2","_attribute_value":"jobVal2"}]
> {code}
> In my opinion, in all the above cases the API should always return a JSON
> array for those elements that can occur with cardinality > 1.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
