Arrays of Nested Objects

[Doug Kaye]

Miel discovered a critical inconsistency, and unfortunately the fix is not obvious. The documentation currently says:

JSON-formatted responses have the following characteristics:

1. There is no explicit object wrapping the response.
   
2. All arrays are named. (eg, An array of collection objects is typically named 'collections'.)
3. All nested objects are named, typically with the object's class name.
4. Objects as elements within arrays are not named.

There are some potential contradictions in the above. And as Miel wrote, at least one of the API methods is returning data that don't match these statements. To demonstrate the issue, consider the two variations of fragments of JSON responses to a /feed request and an XML equivalent:

A:  Array of named/wrapped "program" objects:
{   "id":"144",
    "submitted":1260922826,
    "programs":[
        {"program":
            {   "programId":"5651",
                "title":"David Wang Network",
                "runtime":"1330"}},
        {"program":
            {   "programId":"5652",
                "title":"Randall Julian",
                "runtime":"3253"}}]
}

B:  Array of anonymous "program" objects:
{   "id":"144",
    "submitted":1260922826,
    "programs":[
        {   "programId":"5651",
            "title":"David Wang Network",
            "runtime":"1330"},
        {   "programId":"5652",
            "title":"Randall Julian",
            "runtime":"3253"}]
}

C. An XML representation of the same:
<feed>
    <id>144</id>
    <submitted>1260922826<\submitted>
    <programs>
        <program>
            <programId>5651</programId>
            <title>David Wang Network</title>
            <runtime>1330</runtime>
        </program>
        <program>
            <programId>5652</programId>
            <title>Randall Julian</title>
            <runtime>3253</runtime>
        </program>
    </programs>
</feed>

The question I have for you is, which is the better JSON representation: A (named array elements) or B (anonymous array elements)?

My *guess* is that you'd prefer B (anonymous) as it's probably somewhat easier to parse using the libraries in most programming languages. So why am I considering A (named/wrapped)? Because it maps directly to/from the XML version. From my perspective, it means I can write the code once and without conditionals. I can even write just the JSON version and then convert to XML. It means less maintenance and a reduced likelihood that bugs will creep in. But that's really my problem, not yours. :-)

So tell me which you like (A or B) and why. And when you do, please also say what OS, programming language and parser (library) you're using.

Thanks.

     ...doug

[Miel Bronneberg]

Hi Doug,

I prefer representation B, for reasons I'll explain below, but first
I'd like to say that what it comes down to, is that it's easier for me
to implement B, but really, that's my problem, not yours :-)

What's most important to me, is that you consistently use the same
representation across all JSON responses. I'd perfectly understand if
you choose to be consistent across JSON and XML.

For my SpokenWord client I use Visual Studio 2008 on a Vista system.
The language is C#. For the RESTful stuff I use the WCF REST Starter
Kit preview 2. The serializer I use is
System.Runtime.Serialization.Json.DataContractJsonSerializer

With representation B, I can do something like this:

public class Collection : IExtensibleDataObject
{
// Lots of other members...

[DataMember(Name = "programs")]
public Programs Programs { get; set; }

public ExtensionDataObject ExtensionData { get; set; }
}

[CollectionDataContract(Name = "programs", ItemName = "program")]
public class Programs : List<Program>
{
}

And so a collection simply contains a list of programs.

With representation A, this doesn't work, because the serializer finds
something else in between the Programs and the Program. I don't know
how to tell the serializer to ignore that. (Of course this may very
well be a consequence my ignorance of these matters; I took this
opportunity to learn about Visual Studio, C#, serialization, JSON and
REST. I'm just a newbie really.) Anyway, for a feed, I now have to do
this to get it to work:

[DataContract(Name = "feed")]
public class Feed : IExtensibleDataObject
{
[DataMember(Name = "programs")]
public FeedPrograms Programs { get; set; }

public ExtensionDataObject ExtensionData { get; set; }
}

[CollectionDataContract(Name = "programs", ItemName = "program")]
public class FeedPrograms : List<InBetweenProgram>
{
}

[DataContract()]
public class InBetweenProgram : IExtensibleDataObject
{
[DataMember(Name = "program")]
public Program Program { get; set; }

public ExtensionDataObject ExtensionData { get; set; }
}

And so a feed contains a list of "InBetweenPrograms", each of which
contains nothing but a program.

But as I said, this really is my problem, not yours. I mostly want
SpokenWord to be consistent.

Thanks, regards, Miel.

> --
>
> You received this message because you are subscribed to the Google Groups
> "SpokenWord.org APIs" group.
> To post to this group, send email to spokenw...@googlegroups.com.
> To unsubscribe from this group, send email to
> spokenword-ap...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/spokenword-api?hl=en.
>

[Doug Kaye]

Any other opinions on A vs. B?

   ...doug

[Ken Kennedy]

I use simplejson in Python on Linux and Windows, mostly. I'd prefer B, it's simpler, but it's not critical.

"Programs" in A is kind of goofy, since it looks like a hash/dictionary of dictionaries at first glance, but it's not (since the key "prograrm" is identical every time). So it's a list of single member dictionaries of dictionaries (If I'm writing that correctly...I get the description of those composite datatypes backwards about half the time!). Should be just another layer of indirection for the parsing, though.

--

You received this message because you are subscribed to the Google Groups "SpokenWord.org APIs" group.
To post to this group, send email to spokenw...@googlegroups.com.
To unsubscribe from this group, send email to spokenword-ap...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/spokenword-api?hl=en.

--
Ken Kennedy
Contact info: http://kenzoid.com/me/contact

[Thilo Planz]

> I use simplejson in Python on Linux and Windows, mostly. I'd prefer B, it's
> simpler, but it's not critical.

> Should be just another
> layer of indirection for the parsing, though.

Agree with that.
I have not even looked closely at A versus B, because it just does not
matter too much. You can make parsers for either without much trouble.

Thilo

[Doug Kaye]

Here's where we are on this...

1. Everyone agrees that we should be consistent.

2. The consensus -- and I agree -- is that option B (arrays of anonymous objects) is preferred.

3. Of the five methods that return arrays of objects, it appears the only one that doesn't follow this convention is /feed.

4. Therefore, I propose to change /feed from option A to option B.

5. This will break the code for anyone using /feed.

6. I propose to deploy the change in about 30 hours: 12:01AM Pacific time Tuesday, December 22.

=====

Who is using /feed at this point? I'll check the API logs, but I have a feeling it's only one or two people so far.

IF YOU HAVE A PROBLEM WITH THIS DEPLOYMENT, please let me know ASAP. I can (a) delay the deployment or (b) reconsider the strategy.

Thanks to all for your feedback!

   ...doug

[Miel Bronneberg]

Hi Doug,

I use /feed, and I applaud your choice to go with B. I'll be glad to
clean up my code after you made the change.

Thanks, regards,

Miel.

[Ken Kennedy]

On Sun, Dec 20, 2009 at 9:14 PM, Doug Kaye <do...@rds.com> wrote

=====

Who is using /feed at this point? I'll check the API logs, but I have a feeling it's only one or two people so far.

IF YOU HAVE A PROBLEM WITH THIS DEPLOYMENT, please let me know ASAP. I can (a) delay the deployment or (b) reconsider the strategy.

I have code that uses /feed, but it is very, very dev at this point, so there's no issue. I just ran test suite w/ 0 errors, I'll run again tomorrow, note the errors, and make the needed changes. No problem.