Why do we care about Google Calendar API?
Reuse
Developers reuse all the time - libraries, application servers, even "Googling" for errors. Using remote API is quite the same, but in larger scale.
Integrate
Nowadays, most popular web resources offer remote APIs. Google is one of them. It offers wide range of services that people use in everyday life, covering many trivial and not so trivial tasks that might be required in your project. And guess what? Google wants to share it with you! For this purpose they offer impressive amount of different APIs. One of them is Google Calendar API and today we are going to focus on that. If you are not that interested in calendar, this blog still might give you some hints about other APIs, because there are many things in common.
What can you do with it?
Once upon a time we had a research project. It was not about remote APIs. It was about using HTML5 for mobile development. At the same time, we wanted to make something useful. That's how Conference App was born.
Idea behind this application is to make a convenient conference schedule for mobile devices. Idea comes from personal experience, as many people from our company visit conferences and some even organize them. Usually, schedule printed on paper is either informative or compact, but not both at the same time.
Some time ago I used Google calendar for storing conference schedule and it worked. I was able to enter all events on my laptop, I was able to check the schedule on my Android device and I was able to share this calendar. However, it was a bit inconvenient. Mainly because of the way how many events happening at the same time are displayed.
Our application was supposed to take all the good stuff, fix the bad stuff and put it into conference context. Google Calendar desktop UI can handle lot's of complex stuff, but it comes with a price. We removed all the complexity and left only what is need for current task.
This is a screenshot from conference app. It shows exactly the same calendar.
Idea behind this application is to make a convenient conference schedule for mobile devices. Idea comes from personal experience, as many people from our company visit conferences and some even organize them. Usually, schedule printed on paper is either informative or compact, but not both at the same time.
Some time ago I used Google calendar for storing conference schedule and it worked. I was able to enter all events on my laptop, I was able to check the schedule on my Android device and I was able to share this calendar. However, it was a bit inconvenient. Mainly because of the way how many events happening at the same time are displayed.
Our application was supposed to take all the good stuff, fix the bad stuff and put it into conference context. Google Calendar desktop UI can handle lot's of complex stuff, but it comes with a price. We removed all the complexity and left only what is need for current task.
This is a screenshot from conference app. It shows exactly the same calendar.
How does it work?
Now we are done with introduction and will move to stuff that should interest developers a bit more. Let's see some technical details.
REST
Google Calendar API 3 uses REST. Payload is JSON. It replaced Atom based GData protocol. Old version 2 API is still there, but I'm not sure if it will be discarded at some point. Actually, initially our Conference App was using version 2 and I migrated it to version 3 only when started preparing this blog post. Migration to new version is not very tricky. There is a nice migration guide. If you are still using API v2 - migrate.
Client libraries
REST API assumes that you can make requests to it using any HTTP capable tool and format of requests and responses is described in details in reference documentation. However, Google APIs are quite complex and it is highly recommended to use client libraries. Client libraries are available for quite a large amount of languages and frameworks.
Python is in the center, because this is the only library that does not have "alpha" or "beta" status. Libraries above Python have "beta" status and libraries below have "alpha" status. We used Java library and did not have any significant issues, even though it has "beta" status.
Collections
As any other well structured REST API, Google Calendar API is split into collections of resources.
- ACL
- CalendarList
- Calendars
- Colors
- Events
- Freebusy
- Settings
Most of those collections support CRUD operations. Some support only a subset of CRUD. Some have extra operations. This is a typical set:
- delete
- get
- list
- insert
- update
- patch
- ...
Putting it all together
This is a Java sample that takes event summary from each item in "Events" collection. Parameter to "list" method is not a real calendar id, so sample will not work.
Events events = calendar
.events()
.list("eimems5@group.calendar.google.com")
.execute();
for (Event event : events.getItems()) {
event.getSummary();
}
.events()
.list("eimems5@group.calendar.google.com")
.execute();
for (Event event : events.getItems()) {
event.getSummary();
}
Quite easy. If someone has seen second version of this API, he will notice, that now it takes much less code.
Authorization
Idea behind OAuth2 authorization is quite simple and elegant, but implementation is not always that obvious and it is another reason for using client libraries.
By the way, there is a simpler OAuth version 1 that you can use, but version 2 is preferred.
Different applications (and even different devices) require different authorization flows and Google has something to offer.
Client-side applications
JavaScript-centric applications. These applications may access a Google API while the user is present at the application.
JavaScript-centric applications. These applications may access a Google API while the user is present at the application.
Web server applications
These applications may access a Google API while the user is present at the application or after the user has left the application. This type of access to a Google API is called
offline, since the user does not have to be present at the browser.Installed application
These applications are distributed to individual machines. These applications may access a Google API while the user is present at the application or when the application is running in the background for long periods of time without direct interaction with the user. Like email checking in Android device.
Device applications
Applications that run on devices with limited input capabilities (e.g. game consoles, video cameras, printers) may access an API on behalf of a user, but the user must have separate access to a computer or device with richer input capabilities.
Service accounts
Service accounts can be used on behalf of an application when it does not access user information or accesses publicly available information. Used to identify application. Our application uses this scenario.
Scopes
Each authorization request provides scope that it want's to access. In other words, application might have a permission to read your calendar events, but without modification option.
Google will ask the user if he agrees with requested permissions.
Limits
Almost all Google APIs have limits, which is quite logical. For example, Calendar API has a limit of 10000 requests/day. In some cases it is possible to exceed the limits for extra fee according to the price list. In case of Calendar API there is no price list, only a form that you can fill to request quota changes. Not sure how it works, never tried. 10000 requests per day was more than enough for our project due to long time caching and the fact that we are using only one calendar. Basically this means that we are making only about 144 requests per day.
In case if your app is accessing user calendars, then amount of requests will depend on the amount of users. For this case, there is another limit that you can set in Google API Console - requests/second/user. Default is 5, but you can set it yourself. Personally, I think that you should use this feature only as a last resort and control it in application.
Other services
As I said before, Google offers APIs for quite a large range of services. Here are some of them. Don't be confused with font sizes in this cloud. Bigger font means my personal interest. Hope you can find something interesting for yourself!
