Calendar management
Embedded contextual email
Scheduling automation
Automated outreach
Telehealth
Marketplaces
Recruiting
Document management
Real estate
Communications software
Docs
SDKs
Tutorials
API status
Changelog
Support
Blog
Events
Guides
Newsroom
Partners
Build vs. buy
Customer stories
Trust & security
Why NylasThe 5 Biggest Calendar API Integration Roadblocks
The most basic calendar integration can have unexpected challenges. Learn how the Nylas Calendar API makes it easy.
The most basic calendar integration can have unexpected challenges. Learn how the Nylas Calendar API makes it easy.
Incorporating scheduling functionality into your app can seem quite simple on the surface, but the reality is that the calendar API ecosystem can be fraught with roadblocks and complications. Maybe you want to implement functionality like scheduling a meeting at a time where multiple users are free, or search for a specific type of event across all of a user’s calendars. Most calendar providers have an API, so it should be easy to build these capabilities yourself, right?
Not so fast! Once you start digging into the details of your integration, you’re likely to find out that many calendar APIs are missing crucial capabilities that drastically increase the amount of effort you’ll need to undertake to deal with. Not to mention, every calendar API has its own conventions for how to handle common tasks, and these conventions are typically optimized for the needs of the calendar provider rather than developers who are trying to implement scheduling functionality for their own app.
This blog post will cover the 5 biggest roadblocks you’re likely to encounter when integrating a calendar API into your app, and how Nylas is the best solution for developers who need to integrate scheduling functionality.
Most calendar service providers, like Google, Exchange, Office 365, and Outlook, have their own APIs that each have unique characteristics. The more providers you want to work with, the more technologies, protocols, and frameworks you’ll need to incorporate into your stack. The next table provides a sample of the technologies some of the major calendar providers use.
| Google Calendar | EWS | Microsoft Graph | iCloud | |
|---|---|---|---|---|
| Communication Protocol / Framework | REST | SOAP | REST | HTTP / CalDav |
| Data Type | JSON | XML | JSON | iCalendar |
| Authentication | OAuth with Refresh Token | OAuth | OAuth | Basic |
| Notifications | Webhooks | Webhooks | Temporary Webhooks, Deltas | None |
The complexity of the Calendar API ecosystem is what led to the creation of the Nylas Calendar API, which provides a single point of integration that automatically connects your app to 100% of calendar providers. With Nylas, you don’t need to worry about incorporating multiple authentication services, data types, and notification systems. Instead, you build one integration with Nylas and we abstract away all of these differences.
Most Calendar APIs treat events as second-class objects, meaning that you must know which calendar an event is on before you’re able to work with the event. In this situation, a GET request for a single event typically requires you to pass both the calendar ID and the event ID:
curl -X GET https://api.example.com/calendars/{calendar_id}/events/{event_id}
This might not seem like much of a problem on the surface. However, if you need to handle scheduling use cases that span multiple calendars, whether it’s an individual with multiple calendars or a group of people who each have a single calendar, using an API that treats events as second class objects can dramatically complicate your integration. You might be forced to make bulk requests for every single calendar a user has to find the single event that you want to manage. Alternatively, you’d need to keep your own event database that’s optimized to filter events across all of your users’ calendars.
The Nylas Sync Engine solves this problem; since we sync all of a user’s events, we’re able to treat them as first-class objects and make them much easier to work with. With Nylas, you can get all of the events a user has across all of their calendars with a single GET request to the Events endpoint:
curl - X GET https://api.nylas.com/events
This request returns a list of JSON objects that represent the user’s events, and they each have a calendar_id attribute to indicate which calendar the event exists on if you need to get more information about related calendars:
{
"object": "event",
"title": "On-site Consultation",
"description": "Let's do some on site testing of our latest spacefaring ornithopters.",
"location": "Launch Pad",
"participants": [
{
"name": "Katherine Johnson",
"email": "kat@spacetech.com",
"status": "confirmed"
},
{
"name": "Leonardo Da Vinci",
"email": "leo@ornitech.com",
"status": "confirmed"
}
],
"when": {
"object": "date",
"date": "2145-02-13"
},
"status": "confirmed"
}
One of the most important capabilities when building a scheduling integration is being able to identify the availability of one or more users so you can schedule new events at a time that works for everyone’s schedule. Many calendar API providers offer a free-busy resource that lets you identify periods of time when a user has indicated they are busy with an event. This can be effective for fairly simple availability use cases that involve a single user, but expanding beyond this requires a fairly large amount of custom code.
A much more common scenario is comparing the availability of multiple individuals to find times that work for everyone. This requires additional development effort to extract free-busy information for each user and find times that aren’t blocked by one or more individual’s busy slots.
Fortunately, Nylas has a few tools up our sleeves to help make this process easier. To start, we offer the Availability endpoint that lets you pass in any number of email addresses for people who your user has the ability to view their busy information. This means that you can compare two or more individuals with a single API request:
curl -X POST 'https://api.nylas.com/calendars/availability' \
-H 'Authorization: Bearer access_token' \
-d '{
"duration_minutes": 30,
"start_time": 1600890568,
"end_time": 1600999200,
"interval_minutes": 10,
"emails": [
"tom@brightideas.com",
"jane@brightideas.com"
]
}'
Nylas also offers the Consecutive Availability endpoint that allows you to find consecutive time slots to schedule events between your user and a list of provided email addresses. This endpoint lets you define the event’s duration, relative start time (top or bottom of the hour, 15 minutes before or after the hour, etc.), and if there should be a time gap between each event:
curl -X POST 'https://api.nylas.com/calendars/availability/consecutive' \
-H 'authorization: Bearer <access_token>' \
-d '{
"duration_minutes": 30,
"start_time": 1605794400,
"end_time": 1605826800,
"interval_minutes": 10,
"emails": [
["kat@spacetech.com", "dorothy@spacetech.com"]
]
}'
Not all events a user receives show up in their default calendar app, sometimes they arrive as an ICS file attached to an email. Some calendar providers automatically convert these ICS files into events that show up on the user’s calendar, but this behavior isn’t consistent across email and calendar providers. Nylas automatically creates an emailed events calendar for every user that is connected to our platform and we auto-populate this calendar with data from ICS files that are found in the user’s email inbox. This makes it much easier to work with events that people outside your user’s organization have sent to your user via email and it ensures that no events are left out when working with the Nylas Calendar API.
Any application that manages events across regions must contend with the tricky problem of normalizing time. Many calendar APIs default to returning the event times in the user’s default time zone. This is a convenient behavior for applications that only operate in the context of a single user’s calendar. However, if you need to compare events across different calendars or users, you should always provide a time zone parameter or normalize events in your app’s code.
The Nylas Calendar API normalizes time representations to either a date representation or epoch time representation. Both can be expressed as a single instance or a span that includes all times/dates between two separate date and time representations. This makes it easier to manage the timing of events across multiple calendars and timezones.
Our goal is to enable developers to build better products. We’re the experts at scheduling integrations so you don’t have to be, and we’ve designed our Calendar API to remove many of the roadblocks developers face when building scheduling functionality, letting you focus more on the features your users love. The benefits of Nylas don’t stop with the features outlined in this article, we also protect our customers from third-party API downtime, and we have a front-end Scheduler that you can launch in as little as 5 minutes. If you’re ready, start building with Nylas for free.
Please enter your email address and receive the latest updates.
Ben is the Developer Advocate for Nylas. He is a triathlete, musician, avid gamer, and loves to seek out the best breakfast tacos in Austin, Texas.
