Why do we need an alias?

Kloudless’ Unified Calendar API allows developers to integrate with Google Calendar, Outlook Calendar, CalDAV, and iCalendar (via CalDAV). While recently adding RSVP functionality to the Unified Calendar API, we noticed we could improve the API by adding a way to represent the primary or default calendar without knowing its alphanumeric ID.

The primary calendar is the default calendar that Google, Outlook, and CalDAV calendar services provide based on your email. This is used to receive event invitations if someone invites you to a calendar event, which will then appear on your primary calendar. However, usually this primary calendar has a specific ID, and it does not make sense for a developer to first make an API request to retrieve this ID. We can use an alias called primary both internally and externally to represent this calendar, and you can easily retrieve and respond to any event notifications.

How do we support the primary alias?

First, let’s look at the request a developer would make to our Kloudless Calendar API. Whenever the calendar_id parameter is specified, we need to replace it with the alias primary, starting within the URL. We’ve shown a request that creates a new event for the primary calendar:

You can see we specify primary in the request URL, and we receive an alphanumeric ID for the primary calendar in the response body (for ease of readability and security, we simplified the response body and masked part of the calendar ID).

The API server realizes that primary is equivalent to fdWVld2JkQGdtYWXXXXXXXX, but how did we do that? Intuitively, we need to retrieve the primary calendar ID first for any API request that uses the primary alias.

We’ve provided some sample pseudocode for creating a calendar event:

How do we retrieve the primary calendar from our upstream services? Let’s see what the differences are between Google Calendar, Outlook Calendar / Exchange, and CalDAV.

Google Calendar

Fortunately, the Google Calendar API already supports using the primary shortcut. We can retrieve the primary calendar by sending a request to the following endpoint:

Outlook Calendar / Exchange

Unlike Google Calendar. Outlook Calendar and Exchange have different endpoints based on which calendar to query. We can use the following endpoint to retrieve the primary calendar.

CalDAV

CalDAV is the most complex. The primary calendar concept, named CALDAV:schedule-inbox-URL, is defined in RFC 6638 which is a scheduling extension to CalDAV. In addition, CALDAV:schedule-inbox-URL is not a required property. Therefore, not all of the CalDAV servers have the primary calendar. We have to check whether the server supports RFC 6638 and CALDAV:schedule-inbox-URL property. If not, then we use the first calendar as the primary calendar.

We’ve provided another snippet of pseudocode:

How to use the primary alias in the Unified Calendar API

Our unified API supports using the primary alias for the calendar_id parameter, including:

• Any CRUD operations for the primary calendar
• Finding availability on the primary calendar
• Any CRUD operations for primary calendar events
• Activity monitoring for the primary calendar

Here are a few examples:

Retrieve the primary calendar

Find availability of the primary calendar

List events in the primary calendar

Monitor activity for the primary calendar

Conclusion

Kloudless provides the very useful primary alias for developers to use when querying the primary calendar. Sign up for a free account to try out our calendar API.

Reference

• Google Calendar API Document
• Outlook Calendar API Document
• RFC 6638