CalDAV and the Cronofy API

Author: Garry Shutler

1st December 2016

Something we’re asked from time-to-time is why we didn’t use the standards of CalDAV and iCalendar, instead going for a custom HTTP+JSON API.

CalDAV and iCalendar are great, of the APIs and formats we integrate with they are probably the best. From our point of view the only feature it is lacking is change notifications. However, as Boromir put it:

Boromir - One does not simply implement CalDAV

The problem with CalDAV

CalDAV is great, it makes it possible to do all sort of things, and therein lies the problem. As we support multiple calendar providers, we often have to simplify things to support the lowest common denominator. CalDAV is essentially the highest common denominator of calendar providers and so if we were to expose a CalDAV interface to our service, then there would often be a lossy translation of concepts, or we’d have to support a subset of CalDAV which would be more confusing than not supporting CalDAV at all.

The problem with iCalendar

Hand-in-hand with CalDAV comes iCalendar, so much so that many people use the two interchangeably. Similarly to CalDAV, iCalendar is the highest common denominator of calendar serialization formats, with every attribute you would expect to find, and the ability to define custom ones. Therefore, the problem with iCalendar is similar to the problem with CalDAV: when using iCalendar there’s an expectation as to what that means. To implement a subset of iCalendar would likely be as confusing as not using it at all.

A second problem with iCalendar is that it isn’t a format that most developers are used to. Though it is an elegant format, it’s not the sort of format you can easily pick up and implement yourself. There’s correct wrapping of long lines to deal with, escaping of attributes and other fun things like that. The sort of thing that developers have become accustomed to not worrying about when using formats like XML and JSON.

Decisions must be made

In the very beginning we had to chose one protocol and one serialization format as supporting and developing more would not be a sensible use of time.

There’s often open source libraries to encapsulate the details of CalDAV and iCalendar in your language of choice but that’s often a hurdle too far for companies and we have to maximise our reach. Therefore, it became a choice between JSON and XML, and JSON won out because whilst XML has its merits, it is still tainted with the taste of SOAP.

We looked at other APIs out there and decided to go with vanilla HTTP as it is simple and commonly understood.

However, we did not throw the baby out with the bath water. Whilst we did not implement CalDAV and iCalendar, we have used them to influence our API, benefitting from the knowledge and expertise engrained into them to make better choices for our API.

Of course all decisions are temporary. Just because we’re not CalDAV and iCalendar doesn’t mean we’re never going to support them. Through content negotiation we could add support for CalDAV and iCalendar in the future if it makes sense and the demand is present. However, so far at least, the design of our API has not been a problem for our clients, quite the contrary. By choosing protocols that developers are already experienced with we’ve been able to dramatically reduce the development effort and time for them to deliver calendar sync features to their customers.

Avatar of Garry Shutler

Garry Shutler

Date: 1st December 2016 | Category: Cronofy