Kloudless Blog

Tutorials, case studies and how-tos from our experts

Extending the Kloudless API with custom requests

What a Unified API provides

The process Kloudless uses to create a Unified API could occupy an entire blog post of its own, but a synopsis is that Kloudless identifies the core value proposition of a category of software apps, such as CRM or Cloud Storage services, and defines API endpoints and data models that capture this value. As part of this, Kloudless considers the most popular applications within that category, such as Office 365, Google Drive, Dropbox, and Box in cloud storage, and their APIs.

Some third-party applications don’t support features Kloudless includes in its API definition. In this case, Kloudless attempts to “fill in the gaps” and build on top of the available information to meet the Kloudless API’s standard. An example of this is the Kloudless Events API. Not all third-party apps support detailed event metadata and webhook notifications. The Kloudless backend adopts various techniques, ranging from long-polling and webhooks to A* search, to identify new activity and updated objects in third-party services. Kloudless then provides this data in a common format via easy-to-use API endpoints and webhook notifications.

However, apps within each category, be it Cloud Storage or CRM, continually attempt to differentiate themselves from each other. As apps specialize and enable new uses on their platforms, their APIs evolve as well. For example, the Dropbox API includes Dropbox Paper as well as metadata templates, while the Box API supports watermarks, retention policies, and legal holds. This means that the Kloudless unified API doesn’t cover every single API endpoint developers may need to access from a third-party service. Hard to believe, right?

Fortunately, Kloudless provides ways to access these service-specific API endpoints without having to develop entirely separate integrations that require re-authenticating users, abandoning the abstraction layer’s benefits, or handling common issues such as rate-limiting. Here are the three most important concepts to keep in mind when apps need to access or modify data or functionality specific to a service that is not available via the Kloudless unified API:

  • The Pass-through API allows arbitrary API requests to any upstream API endpoint and handles common tasks such as authorizing requests, refreshing OAuth tokens, and rate-limiting.
  • Most Kloudless API endpoints support including the raw data from the upstream service in the response. This is valuable to access service-specific attributes that Kloudless doesn’t parse into a unified format. Set the X-Kloudless-Raw-Data: true header in the API request to enable this. Similarly, several API endpoints also support sending raw data to merge directly into the upstream HTTP JSON body when creating or updating objects. For example, the CRM API endpoint includes a raw attribute when creating an Opportunity.
  • Apps can use the ID conversion endpoint to convert Raw ID information into Kloudless IDs for use with the unified API.

Below, we’ll cover how to use these together.

Retrieving Raw Data

When apps make requests to the Kloudless API, Kloudless parses responses from the upstream API and converts it into the Kloudless data format expected. Developers can retrieve the raw upstream data that Kloudless parses by including the X-Kloudless-Raw-Data: true header in requests (docs). This requests the Kloudless API service to return the raw unparsed data in the response. Here’s an example when retrieving a SharePoint folder’s metadata:

The data in the response below contains a raw ID within raw->id in the form that the Kloudless API encodes it from. The corresponding encoded ID is present in the unified metadata’s id attribute.

The response above also contains the folder creator’s raw identification information, as well as several other SharePoint-specific attributes within raw->object.

Retrieving Raw Data with the Pass-through API

Another way to retrieve raw data is to use the Pass-through API. Here’s an example that retrieves raw SharePoint Document Library information in an account’s primary SharePoint site:

The Kloudless API returns the Office 365 Graph API’s response directly:

The response above also includes the most recent editor’s unique GUID, as well as the Document Library folder’s unique ID.

Either approach taken, the raw IDs and other attributes help with subsequent pass-through requests to the upstream API’s native endpoints, such as the Box watermarking API mentioned earlier.

Using a custom upstream API endpoint with Kloudless data

The pass-through API request’s response frequently needs to be used with the rest of the Kloudless API. For example, an application may need to create a new directory role (group) in Office 365 via the native Graph API, using Kloudless’s pass-through endpoint, and then add users to this group via the Kloudless API as well as identify the group in Kloudless Events that it subsequently appears in.

Since Kloudless provides IDs in an encoded format, this requires the application to convert the raw identification information returned by the Graph API in response to the pass-through request to the Kloudless ID format via the ID encoding endpoint. Here’s an example that converts a user ID:

The response contains an encoded ID for use with regular Kloudless API endpoints:

The ID above may not represent the canonical User ID, which can be obtained from the Users API endpoint. Note that this requires an app to connect an admin SharePoint account via the admin OAuth flow. Contact us for more information and access to the Team API.

The ultimate goal

The process above allows developers to benefit from the Kloudless API’s unified objects, with its ID abstractions, as well as dive into specific functionality of each upstream service when necessary. Combined, this represents a powerful approach to rapidly accelerate an application’s time-to-market with several integrations while not losing access to custom functionality between the application and a specific third-party service.

Published By

Vinod Chandru