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.

 

Calendar API: Activity Stream

This post is by our engineering intern, Ellen Luo.

Receive real-time updates for Google and Outlook Calendar with the new Events endpoint for the Calendar API!

The Events endpoint allows your application to easily keep track of calendar items that have been added, modified or deleted in your primary calendar. This Events endpoint is part of our broader Events API to monitor activity in connected accounts, and should not be confused with the Calendar Events API that enables access to calendar appointments.

Retrieving activity data with the Events API

To start using the Events API, check the box beside “Collect Events” in the App Details page of the Developer Portal. Kloudless will automatically begin to collect activity data for any newly connected Google or Outlook Calendar accounts. Google Calendar allows real-time updates of changes to users’ accounts so event data is updated in at most 1.5 minutes. For Outlook Calendar, Kloudless queries the service repeatedly to find changes. This means that event data will be updated on average every 15 minutes in our cloud and 1-5 minutes in private installs (configurable).

Requesting activity data

To return a list of all recent events collected, make a request to https://api.kloudless.com/v1/accounts/{account_id}/events/ with your connected account’s ID and Bearer token (or application API Key). A sample request is shown below:

curl -X GET -H 'Accept: application/json' \
    -H 'Authorization: Bearer {token}' \
    'http://api.kloudless.com/v1/accounts/{account_id}/events/'

Parsing the response

The response will contain a list objects of all the events. Each object has a type, which indicates the type of change. Right now, the only events that are detected are “add” (object created), “update” (existing object modified), and “delete” (object deleted). Each event object will have the updated metadata of the object modified. More information about the Events API and sample responses can be found in the Kloudless docs here.

Roadmap

In the future, we will add support for retrieving activity data for calendars other than the account’s primary calendar. We will also be working towards including more specific event types and expanding support to more calendaring APIs. We’re excited to make the Calendar API Activity Stream endpoint available to all developers on our platform and would love to hear any feedback or suggestions on Twitter, the comments below, or at hello@kloudless.com.

Announcing the Kloudless Pass-through API

We are excited to announce the general availability of the new Kloudless Pass-through API endpoint. The Pass-through API enables your application to access the full functionality of the third-party software service by performing API requests directly to the service. Kloudless continues to ensure any relevant authentication information like refreshed access tokens are included in the API request.

While Kloudless provides unified APIs, there may be times when your application needs to access unique functionality in a third-party service that is not available in Kloudless’s unified APIs. The Pass-through API solves this problem by enabling your application to send raw data to a third-party API’s endpoint and receive the raw response streamed directly from the service through Kloudless.

Check out our API docs for more information on how to use the Pass-through API.

Kloudless API v1 Launches Today

Last week, we launched our Universal CRM API. You can read more about the announcement here. The new API kicks off our broader product strategy to provide Universal APIs for many important areas of business.

As part of this product launch, we are also launching v1 of our API. Our goal with v1 is to establish a strong foundation for building future products and functionalities.

 

What’s new in v1

The migration to v1 introduces new capabilities and improvements to existing functionality.

Universal CRM API
Previously, the Universal CRM API was only available in Kloudless Enterprise. With v1, the CRM API is available to any developer that prefers to use our cloud version at kloudless.com. You can start integrating the CRM API for free here.

OAuth 2.0
We are introducing a standards-compliant OAuth 2.0 authentication mechanism to connect user accounts, which enables easy integration with other tools that support OAuth 2.0. Other benefits include:

  • Documented support for out-of-band, authorization code grant, and implicit grant OAuth 2.0 flows to support authentication in any environment.
  • More granular scopes to better control the services, APIs and types of accounts users can connect to your app.
  • Improved security with white-listed Redirect URIs, validated Client IDs/Secrets, and verified Bearer tokens.

Read more about Kloudless authentication here.

Other enhancements
As you read through our documentation, you will find small improvements to many endpoints. For example, we’ve updated our old permissions format to support groups and our old pagination format to be more flexible.

 

What this means for you

First, any new applications you develop should use API v1.

Second, there are backwards incompatible changes in the migration from v0 to v1. API v1 is built thoughtfully, and we try to limit the changes you need to your implementation to only the things we consider most important moving forward. You should update your app’s integration with Kloudless as soon as possible.

Here is a summary of the backwards-incompatible changes.

API-namespacing for endpoints
All endpoints specific to the Storage API have been namespaced under /storage/. Learn more

OAuth 2.0 Authentication
OAuth 2.0 authentication is now required. The previous authentication format is no longer supported. OAuth 2.0 Bearer tokens have replaced Account Keys. Learn more

Events
Deprecated event object attributes have been removed. Learn more

Pagination
next_page must be used to identify the next page value for pagination. Learn more

File Uploads
Files are uploaded as binary content rather than via multipart form POST requests. Learn more

Permissions
File/Folder permission updates take in a list of permission objects rather than a mapping of user emails to roles. Learn more

Users of the UI Tools do not need to make changes to use v1, although they would have to make changes to switch to OAuth if using the Authenticator JS library or if using Account Keys from the File Explorer.

None of your users need to re-authenticate when you switch your app to either OAuth 2.0 or the v1 API.

 

Deprecating v0 and the old auth mechanism

As of today, v0 of the API is deprecated. In order to provide you with the most up-to-date features and support a single, consistent API platform, we’ll be turning off API v0 on February  28, 2018.

Our previous authentication mechanism will be turned off in one year on August 31, 2017.

In our next update, we will provide a more detailed deprecation timeline.

We love building for the thousands of developers using our platform. If you have any questions or feedback, we’d love to hear from you in our developer forum.

An Eventful Update

Kloudless developers can now manage their events even more efficiently using the new Events Endpoint updates. Check out what our engineers have been tinkering with below!

Kloudless Enterprise Events

Connect your Admin account and get access to organization-wide events. Enterprise Events can obtained through the normal events endpoint. The user responsible for the event is specified where applicable. 

Events Endpoint Pagination

The Events endpoint now supports requests of a specific page size and also returns the number of remaining events. It also supports only the retrieval events created after the cloud account has been connected to the Kloudless application. Additionally, a more granular list of event types is also now available, instead of + and -.

S3 Event Notifications

Event data and webhook notifications are now available for changes to data in S3 accounts. Any S3 accounts requiring this feature must be reconnected.

Whether you’re using the cloud, private installs, or Enterprise version of Kloudless, this new update enables your application to respond to activity in cloud storage more effectively.

Not a Kloudless developer yet? Click here to get started. Questions or feedback? Feel free to drop a line at hello@kloudless.com

Level Up: A Guide to Kloudless Enterprise Clustering (III of III)

This blog post was authored by David Thorman, who leads Ops at Kloudless.

In our last post we covered the different options for deploying Kloudless Enterprise. When deploying Kloudless Enterprise, you would start off with a single server. However, when running any application, there is a limit to how much work a single server can handle. A server can be scaled vertically by allocating more CPU cores and memory, but eventually those limits will be reached and another mechanism to increase capacity must be found. This is where clustering is useful.

Clustering allows your application to scale out horizontally rather than up which leads to two benefits: higher throughput capacity and high availability. Clustering is made possible by running more than one Kloudless Enterprise instance behind a load balancer. A load balancer is a server that accepts requests from clients and then forwards them to the backend Kloudless Enterprise servers. This allows the client to take advantage of multiple backend servers without having to manually keep track of their hostnames. The distribution of work allows the cluster to handle a higher number of requests than a single server would, resulting in greater throughput.

Screen Shot 2015-09-28 at 8.55.00 PM

The cluster can continue to serve requests in the event of a failed secondary instance, ensuring high availability. If the primary instance fails, a secondary instance will be promoted to primary, ensuring smooth disaster recovery. Each node is capable of handling similar work, and is configured to be the same size. This means the failure of a single node will not result in the cluster not being able to serve requests.

Service interruption can be minimized by ensuring that the load balancer only sends requests to nodes that it realizes are healthy. This is typically achieved via health checks that the load balancer performs. For example, in AWS, the Elastic Load Balancer’s health checks take the form of an HTTP request to each individual node in the cluster. Nodes that either don’t return or return a non-200 status code are marked as unhealthy. This allows the cluster to handle requests successfully even though there are failures.

Thanks to the HA/DR features above, the cluster can be dynamically scaled up or down without interrupting service to clients. Adding new nodes increases capacity when your service experiences periods of higher load. Removing nodes allows costs to be reduced during periods of lower load. On certain platforms ,these changes in capacity can be handled automatically either on a timed schedule or based on metrics gathered from the cluster itself. This allows you to take full advantage of the elasticity of modern IaaS platforms such as AWS without disrupting service to your customers.

This post has covered the high-level benefits of clustering and the flexibility of a Kloudless Enterprise deployment. Our configuration guide covers the technical details of deploying Kloudless Enterprise as well as a walkthrough detailing how to deploy Kloudless Enterprise in an auto-scaling cluster. The guide can be accessed by emailing us at hello@kloudless.com. Feel free to reach out to us or comment below with any questions.

Thanks for following our Kloudless Enterprise Series!

Level Up: You Call the Shots (Part II of III)

In our last post, we introduced Kloudless Enterprise, a version of our software that you can host in your own private infrastructure.

There are actually several options for deploying Kloudless: Cloud, Cloud Private Install, On-premises, and a couple more that we can’t talk about yet. But, we get it. Too many choices, too little time.

Here’s a side-by-side comparison of our current deployment options to help you quickly pick the options that’s right for you:

Cloud

Private Install

Enterprise

Manager Kloudless Kloudless You
Hosted in AWS AWS
Your or your customer’s private infrastructure
Connectors Cloud services only Cloud services only Cloud services + On-premises proxy connector
Scaling Auto-scaled based on total usage across all tenants Auto-scaled based on your usage Scaling managed by you
Availability Kloudless manages high availability Kloudless manages high availability via Enterprise Clustering. Clustering support to enable high availability
Security Data encrypted in transit and at rest. 24/7 Ops team on call Same as “Cloud” except your data is isolated. Access is restricted to your IPs Inherits your security and regulatory compliance promises. No data passes through Kloudless infrastructure

The Level Up mini series is wrapping up soon –don’t miss it! If you can’t wait until our next blog post and want to start using Kloudless Enterprise today, drop us a line at hello@kloudless.com.

Level Up: A Developer’s Intro to Kloudless Enterprise (Part I of III)

Get all the benefits of Kloudless without using Kloudless servers.

That’s right. Now, you choose where your data goes. Introducing, the latest version of Kloudless: Kloudless Enterprise.

Kloudless Enterprise is a virtual appliance that is installed to private infrastructure. This means that you can host Kloudless in your own private cloud or on-premises data center.

Unlike the Cloud or Cloud Private Install versions of our service, the data exchanged between your application and storage services never passes through Kloudless’s infrastructure. Your servers communicate directly with the file storage services.

In the next two blog posts, we’ll cover how Kloudless Enterprise differs from our Cloud Private Install and the security/performance benefits of going on-premises.

On Premises Illustration
Stay tuned for Part II! Interested in hosting Kloudless Enterprise on your own servers? Shoot us an email at hello@kloudless.com.

VIP Kloud Treatment

If you built and deployed an application without contacting us, you are using our Cloud version, which is hosted on Amazon Web Services, multi-tenant, and fully managed by us. However, as the saying goes, “too many chefs in the kitchen can ruin the broth.” (This isn’t the best analogy, plus only we can ruin our broth, but you get the point.).

For a number of reasons (data security, special support requirements, etc.), not all developers want to be part of a multi-tenant facility. That’s why we’re introducing our new VIP service: the Cloud Private Install.

Cloud Private Installs are hosted on an instance in a service provider of your choice (AWS, Azure, Rackspace, etc.), with all features from the Cloud version supported. The installation is fully managed by Kloudless, including all infrastructure requirements, security updates and application upgrades. Based on the performance and availability you need, we can come up with the right instance category and bring up the virtual appliance in the appropriate regions of the cloud provider of your choosing.

Benefits of the Cloud Private Install include:

  • Superior networking performance and data throughput (e.g. Up to 10 Gbps on AWS)
  • Multi-tenant capable: CPU affinity can be optimized for either single or multiple tenants
  • Complementary proxy tool, enabling you to connect to on-premises storage repositories in your customer’s infrastructure
  • Custom SLAs and higher tiers of support

Our Cloud version and Cloud Private Install come with 99.9% uptime and a dedicated Ops team available 24/7, so regardless of which edition you’re using, you’re in good hands.

Interested in becoming a VIP? Get started with a Kloudless developer account and drop us a line at hello@kloudless.com.