Google Calendar API : Events and update

For some of us Google Calendar is a nice way to keep track of events. Then we might decide it will be better to have our own little synchronisation of events between our custom app and the calendar.

In that case we would probably rely on ICS synchronisation or ... one of the many Google APIs.

A rather complete documentation

You can easily find the documentation for the Calendar API : https://developers.google.com/google-apps/calendar/v3/reference/events. Well there is the other one to list calendars and create them, that previous URL is about Events. And events are the important part in what we want to do.

Creating the event

The documentation seems quite complete, at first. Creating an event (https://developers.google.com/google-apps/calendar/v3/reference/events/insert) only requires a calendar id, a description, a couple of dates too. That call will return an id for this new event. That part is a little bit important.

Updating the event

Updating an event is then the next step you probably want to do : making sure that what ever you do in your custom app the google calendar gets updated.

To update an event you need to pass the calendar id again, but also the event id that was returned on the create call. And of course what ever update you want to do. Or so that's what the documentation says.

In practice, that documentation is more like one of those insurance contracts : you need to read the fine prints and in between the lines.
After one or two updates an error would be returned. That error refer to an invalid sequence number.

Asking around and reading the documentation more closely you can understand that you do need to pass a sequence number alongside the data for the event. Do we need to guess the value to pass ?

Turns out that the API will return the sequence number to use for the next call with each response. The first one is 0, and if you don't pass any sequence number it's also the default value used by the API. That explains how the first update happen without trouble.

Cut

Google API documentation has long been a troublesome matter for a lot of us. Incomplete, stuck in between versions, it's a frequent reminder that we, developers and API designers should always make sure our documentation is up to date and clear enough to use.

In the meantime I hope that post reach anyone who is trying to figure out why events can't be update more than 2 times ...

Original post on stack overflow : http://stackoverflow.com/questions/24364004/google-calendar-api-event-update-with-the-ruby-gem