Calendar API: Availability Endpoint now… Available!

This post was written by our software engineer, Ryan Connor.

Finding an appropriate meeting time can take a lot of effort, even with just a few participants who have only a single calendar. Finding a meeting time that is sure to work for many participants with multiple calendars managed by several cloud services? Good luck!

Fortunately, Kloudless now helps you do just that. We are proud to announce that the Calendar Availability endpoint is online and ready to help your application find meeting times that work for any combination of user accounts and their calendars.

Using the Calendar Availability Endpoint

The Calendar Availability endpoint returns all available time windows among a set of calendars that match a specific meeting duration and desired time windows for the meeting. The endpoint also supports requests involving multiple calendars for multiple accounts.

To illustrate, imagine your app has 100 users who have two personal (Google) calendars and two work (Outlook) calendars for a total of four hundred calendars. One call to the Calendar Availability endpoint can retrieve available meeting times (if any) for all 100 users subject to all four of their calendars. Alternatively, you can retrieve available meeting times for just a subset of users and/or their calendars.

Kloudless seamlessly integrates with Google and Outlook Calendar behind the scenes—all you have to provide are Account IDs, Calendar IDs, a meeting duration, and time constraints. Let’s take a look at exactly how to do that.

Formatting the Request and Parsing the Response

Here are the details for the request and response format of the Calendar Availability endpoint based on our docs. You can scroll down further to see concrete examples.

Request Format

URL: https://api.kloudless.com/v1/accounts/{account_id,account_id,…}/cal/availability

Method: POST

Headers:

  • Authorization: Bearer [Token]
  • Content-Type: application/json

Body:

  • calendars: List of Calendar IDs. Uses the default calendar if empty. (Optional)
  • meeting_duration: ISO 8601 format for duration. (Required)
  • constraints: A dictionary of constraint keys and values. (Required)
    • time_windows: List of desired time slots with the following values.
      • start: ISO 8601 datetime format
      • end: ISO 8601 datetime format

Response Format

Headers:

  • Content-Type: application/json

Body:

  • time_windows: List of desired time slots with the following values.
    • start: ISO 8601 datetime format
    • end: ISO 8601 datetime format

The start and end times of each time_window in the response bookend (inclusively) the time periods in which all of the accounts are available given the constraints. Note that the times are returned in the GMT time zone, so you may want to convert to the time zone of your choice.

Concretely, if the response includes the “2 – 5 PM” time window and you wanted a 30-minute meeting, you can safely schedule the meeting to start and end at any time within 2 – 5 PM, inclusive (e.g., 2 – 2:30, 2:01-2:31, …, 4:29-4:59, 4:30-5:00).

Example Usage

Single account, two calendars specified

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "calendars": ["ra5werWRsZXQzLcRik5BudGltb6RwwUNnbWFpbC5jb21=",
                      "fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=”],
        "meeting_duration": "PT1H",
        "constraints": {
            "time_windows": [{
                "start": "2017-05-20T08:00:00+07:00",
                "end": "2017-05-20T12:00:00+07:00"
            },{
                "start": "2017-05-21T08:00:00+07:00",
                "end": "2017-05-21T12:00:00+07:00"
            }]
        }
    }' \
    'https://api.kloudless.com/v1/accounts/123/cal/availability'

 

{
  "time_windows": [
    {
      "start": "2017-05-20T02:00:00Z",
      "end": "2017-05-20T04:00:00Z"
    },
    {
      "start": "2017-05-21T03:00:00Z",
      "end": "2017-05-21T04:00:00Z"
    }
  ]
}

In this case, the requestor wants to find an appropriate meeting time for a one hour meeting during the 8 AM – 12 PM GMT+7 time window on either May 20, 2017 or May 21, 2017. The requestor is requiring one account as a participant in the meeting and further specifying two calendars from that account.

Note that the primary calendar within an account is automatically considered if no calendars are provided. But, if any calendars are provided, the primary calendar must be included to be considered. For example, if the primary calendar ID in this case is neither ra5werWRsZXQzLcRik5BudGltb6RwwUNnbWFpbC5jb21= nor fa2xvdWRsZXNzLnRlc3QudGltb3RoeUBnbWFpbC5jb20=, the primary calendar would be ignored when retrieving availability. To also consider the primary calendar, the requestor should provide it as a third calendar in the given calendar list.

The response indicates that any one-hour slot between either 9 AM – 11 AM GMT+7 on May 20, 2017 or 10 AM – 11 AM on May 21, 2017 works for the meeting. Of course, the desired meeting length is exactly as long as the boundaries of the second available time window, so there is only one slot that works on that date.

Multiple accounts, no calendars specified

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "meeting_duration": "PT45M",
        "constraints": {
            "time_windows": [{
                "start": "2017-06-15T08:00:00-03:00",
                "end": "2017-06-15T17:00:00-03:00"
            }]
        }
    }' \
    'https://api.kloudless.com/v1/accounts/123,456,789/cal/availability'
{
  "time_windows": [
    {
      "start": "2017-06-15T05:00:00Z",
      "end": "2017-06-15T06:30:00Z"
    },
    {
      "start": "2017-06-15T07:45:00Z",
      "end": "2017-06-15T10:00:00Z"
    },
    {
      "start": "2017-06-15T12:30:00Z", 
      "end": "2017-06-15T14:00:00Z"
    }
  ]
}

Here, the requestor wants to find a time for a 45-minute meeting during the 8 AM – 5 PM GMT-3 time window on June 15, 2017. The requestor is requiring three accounts as participants in the meeting, and since no calendars are specified, is searching for availability based solely on each account’s primary calendar.

Note that you can pass time window start and end times in any time zone (and, in fact, differing time zones within the same request). Furthermore, the calendars to be searched on need not be in the same time zone as the constraints. The important point is that the times are passed as ISO 8601-formatted strings—Kloudless will handle the rest.

The response indicates that any 45-minute slot between 9 AM – 10:30 AM GMT-3, 0:45 AM – 1 PM GMT-3, or 3:30 – 5 PM GMT-3 on June 15, 2017 works for the meeting.

Looking to the Future

The Calendar Availability endpoint provides a simple way to coordinate meetings among multiple calendars and calendar accounts. Going forward, we will monitor usage of the endpoint and listen to your feedback to determine the best way to expand the endpoint’s functionality and flexibility. We already have some great suggestions for making the endpoint more customizable, including:

  • The start_times constraint. If the requestor provides start_times in addition to (or in lieu of) time_windows, the endpoint would return the subset of start_times that work as the start time for the meeting. Essentially, this lets the requestor ask “Which of these exact start times are OK for the meeting?”
  • The ​min_attend_percent constraint. Right now, a time window will only be included in the response if every given account is available in that window—that is, if one relevant calendar in one account is not available during a window, that account is not available and so that window is not returned. With the min_attend_percent constraint, a time window would be included if at least the specified percentage of accounts are available during that window.e
  • The work_or_personal constraint. The requestor could provide a work_or_personal argument to limit the times considered for work or personal hours. This could be especially useful when trying to coordinate across widely varying time zones. For example, a colleague across the world may technically be “available” for a meeting at the time the requestor desires, but that’s of little use if it’s 2 AM for that colleague!

Wrapping Up

We’re excited to rollout the Calendar Availability endpoint to the developers on our platform. What do you like about the endpoint right now, what questions do you have about it, and what do you wish it would do in the future? We would love to hear your thoughts and feedback on Twitter, our developer forums, comments below, or at hello@kloudless.com.

 

How to connect with 1.2 billion Microsoft users

Last week at the Connect(); conference in New York, Microsoft publicly unveiled the Microsoft Graph, a unified API that enables developers to tap into Microsoft’s 1.2 billion users around the world.

There is a lot going on in the Microsoft Graph, but we will look closely at the file storage services: OneDrive (OD), OneDrive for Business (ODB), and SharePoint Online (SP).

What is the Microsoft Graph

Microsoft Graph is a unified API for connecting to Office 365.

Previously, each Office 365 service was silo’d and had its own unique API. This required developers to obtain separate access tokens and call different endpoints for each service they wanted to integrate with.

With the new unified API, features, data, and insights across Office 365 services can all be accessed from a single API.

That’s nice but..

Historically, Microsoft has not been great with APIs. Services often have multiple versions, each with multiple APIs spanning hundreds of pages of documentation.

Our implementations of OD, ODB, and SP pull from several different APIs in order to get comprehensive feature and data coverage. Of course, developers that use Kloudless are shielded from this complexity, since we offer a universal interface for integrating file storage services.

Getting started

If you’re not a Kloudless developer yet, this means that you’ll have to go through another proprietary API, integrate it into your application, and maintain it in the long run. You can read through the documentation and try out the Microsoft Graph at graph.microsoft.com.

If you have an existing integration with Office 365 service, make sure to check for feature parity between the old APIs and the new unified API before overhauling you current implementation.

We noticed several differences. Some features like adding an admin user as a site collection administrator SP are only found in the old SP APIs. Other features like listing all site collections (SP) and personal sites (ODB) are only available in the new Microsoft Graph API.

For use cases that only require basic operations, you’ll be fine switching over to the new API. Otherwise, like us, there’s a good chance you’ll find yourself mixing and matching APIs to get everything you need.

If you are using Kloudless, you’re already integrated with the Microsoft Graph! We’re dedicated to bringing you the latest and greatest, so we worked with Microsoft earlier this year to get our hands on a preview of a couple unreleased APIs, including the Office 365 Unified API.

As a result, no extra work is required to transition to the Microsoft Graph, because we’ve taken care of everything under the hood. You will automatically receive all the improvements and new features.

New features supported in Kloudless

You can access new Microsoft features via the respective Kloudless endpoints.

Events and Notifications (ODB, SP) – Real-time notifications for what’s changed in a folder.

Permissions (OD, ODB, SP) – Adding, modifying, and removing permissions on files and folders. (Coming soon)

What we think about the new Graph

We like all the talk coming out of Redmond. Unifying APIs is a mission that we can get behind.

However, a few challenges remain if you’re looking to integrate file storage APIs into your application:

  1. Uniform APIs are a great promise, but execution and timeliness matters. A few years in, OneDrive and OneDrive for Business still have many API differences.
  2. It sounds like a lot of updates are planned. If you plan on integrating directly with the new API, be prepared for several rounds of maintenance work in the near future.
  3. The Microsoft Graph will not unify the other 25+ file storage APIs like Box, Dropbox, Google Drive, Egnyte, etc.

This is definitely a step in the right direction for Microsoft to endear themselves with developers. It certainly makes our job a bit easier.

Kloudless unifies 25+ file storage services under a universal API. If you’d like to easily integrate the Microsoft services and many others, sign up for a Kloudless account and start developing for free!