JSON

Fortunately, there's an alternative to Atom on the return side. If you put an alt=jasonc argument into your REST request's query sting, you get back a JSON-C version of the data rather than an Atom version. To see the difference, go to the end of this article and look at the XML that Google returns when you ask for a list of all your Calendars (and this is a relatively simple example). A full list of calendar items is much worse.

Now go to the end of this article and take a look at the JSON-C that Google returns for a similar request. It's much better, although still not perfect. Pressing the "author" field in service so that you can display the phrase "Phases of the Moon" is an odd choice, for example.

My main problem with Google's JSON is the way Google has incorrectly used generic tags like "data," "kind," and "items" rather than semantically meaningful names. Instead of

{
  ...
  "data": {
    "kind": "calendar#calendarFeed",
    ...
    "items": [
      {
        "kind": "calendar#calendar",
        ...
      },
      {
        "kind": "calendar#calendar",
        ...
      }
    ]
  }
}

They should have done it like this:

"calendarList": {
  ...
  "calendars": [
      {
        ...
      },
      {
        ...
      }
    ]
  }
}

As with the XML, proper semantic tagging (in the second example) makes it a lot easier to find what you're looking for in a large data set. More to the point, semantic tagging would have made it easy to do automated data binding to POJOs (which JSON libraries like Jackson can do quite handily). Although we can still do that, our POJO will not be nearly as easy to use as it could have been.

The main lesson from the foregoing code is that, in spite of my grousing, JSON is the better choice of return formats. Unfortunately, some of the recent additions to the APIs don't return JSON, so you're stuck with Atom feeds if you have to use those new APIs.

Just for ducks, and taking a clue from the JSON that Google actually does return, here's what the XML could (but does not) look like:

<calendarList 
    apiVersion='2.3'
    canPost='true'
    etag='W/\"AkQBSH8-fSp7IWA9WxBaGEs.'
    id='http:<i>//www.google.com/calendar/feeds/default/allcalendars/full'</i>
    updated="'010-03-29T13:12:39.155Z'
    feedLink='https:<i>//www.google.com/calendar/feeds/default/allcalendars/full'</i>
    selfLink='https:<i>//www.google.com/calendar/feeds/default/allcalendars/full?alt\u003djsonc'</i>
>
    <author displayName="Coach" email="user@gmail.com" />
    <calendar
        etag= "W/\"Ck4FQX47eCp7IWA9WxBaFEk.\""
        id                   =  "http:<i>//www.google.com/calendar/feeds/default/calendars/full/user%40google.com"</i>
        eventFeedLink        = "https:<i>//www.google.com/calendar/feeds/user%40gmail.com/private/full"</i>
        accessControlListLink= "https:<i>//www.google.com/calendar/feeds/user%40gmail.com/acl/full"</i>
        selfLink             = "https:<i>//www.google.com/calendar/feeds/default/allcalendars/full/user%40gmail.com"</i>
        created     = "2010-03-29T13:12:38.877Z"
        updated     = "2010-03-24T14:28:30.000Z"
        title       = "My Primary Calendar"
        canEdit     = "true"
        accessLevel = "owner"
        color       = "#A32929"
        hidden      = "false"
        selected    = "true"
        timeZone    = "America/Los_Angeles"
        location    = "Moutani View"
        timesCleaned= "0"
    >
        <author displayName="Coach" email="user@gmail.com" />
    </calendar>
    <calendar
        etag            = 'W/\"CUMCQX47eCp7IWA9WxBaGEk.\"'
        id              = "http:<i>//www.google.com/calendar/feeds/default/calendars/p%23moonphase%40group.v.calendar.google.com"</i>
        eventFeedLink   = "https:<i>//www.google.com/calendar/feeds/p%23moonphase%40group.v.calendar.google.com/private/full"</i>
        selfLink        = "https:<i>//www.google.com/calendar/feeds/default/allcalendars/full/p%23moonphase%40group.v.calendar.google.com"</i>
        created         = "2010-03-29T13:12:38.861Z"
        updated         = "2010-03-29T06:17:40.000Z"
        title           = "Phases of the Moon"
        details         = "Shows the primary phases of the Moon"
        canEdit         = "true"
        accessLevel     = "read"
        color           = "#AB8B00"
        hidden          = "false"
        selected        = "false"
        timeZone        = "Europe/Zurich"
        timesCleaned    = "0"
    >
        <author displayName="Coach" email="user@gmail.com" />
    </calendar>
</calendarList>

Parsing the Result

Once you have a result, you do have to parse it. There are several great libraries that will do that without difficulty. JDOM is your best choice to work with raw XML. At the Atom level, we have ROME and Eddie, although these are both really overkill for the current application.

If you opt for JSON, which I've done everywhere that I can, there's the somewhat creaky json.org parser, but there's also google-gson and the very fast and powerful Jackson library I mentioned earlier. All are better choices than the Java APIs that Google provides.