In our previous post, we covered how to use the Pass-through API in conjunction with the Kloudless unified APIs to make requests to any endpoint supported by the upstream service. In several cases, apps need to subsequently use data in the response received from upstream APIs with other Kloudless API endpoints. This poses a challenge since Kloudless takes steps to encode IDs to ensure consistency (check out our previous blog post on IDs for how and why we do this). For example, if an app uses the Pass-through API to create a Dropbox user, the app needs to first encode the new user’s ID it receives before using it in Kloudless API requests such as for user impersonation or to move files to that user account.

Fortunately, it’s straight-forward to encode any upstream ID into a Kloudless ID. Apps can send the ID encoding endpoint identification information representing the object to encode. The endpoint returns the ID encoded in the appropriate format for the account’s upstream service. In the example above, the app would need to send over a Dropbox User ID and receive back an encoded Kloudless User ID to use with the Kloudless API.

Encode a larger number of ID types

Until recently, the ID encoding endpoint only supported encoding Storage API file and folder IDs. However, we’ve recently introduced the capability to specify the type and api an ID belongs to, allowing us to expand the types of IDs supported beyond filesystem IDs.

Today, the endpoint supports encoding IDs for users, groups, CRM/ITSM objects, calendar events, and more!

Revisiting our example using users, here’s an API request that encodes a SharePoint user ID:

The response includes the encoded ID for use with the Kloudless API:

Data required to encode the ID

Notice that the request above contains an attribute, userPrincipalName. As per the docs, this is only required for SharePoint and OneDrive for Business, although other services need similar service-specific attributes. The reason for this is that Kloudless includes all information required to uniquely identify an object within a single identification string, and encodes it. This prevents Kloudless from requiring developers to maintain and provide information other than a resource’s ID during API requests, such as the type of Evernote note or Salesforce object. The Evernote and Salesforce APIs may require this type of additional information in several common API requests. Kloudless itself currently requires app developers to be aware of the type of ID used with the API. For a full overview of our thoughts on IDs, check out our past blog post on IDs here.

Shortcuts to encode IDs

Sometimes, gathering the data required to encode a single ID can prove unnecessarily complex. For example, SharePoint groups can either be directory roles or groups, and SharePoint file IDs can have complex query structures within them. Fortunately, a simpler solution exists.

The Kloudless API itself frequently returns decoded raw IDs by setting the X-Kloudless-Raw-Data: true header in requests. In this scenario, the encoding endpoint accepts a single raw_id attribute that exactly matches a raw ID returned by Kloudless via any of the unified API endpoints. This ID contains all the information that would have otherwise been encoded into this very format by the encoding endpoint in the first place.

For example, a raw SharePoint file ID could be of the form :953f306c-7b84-4e07-826c-a682779db88b:getfilebyid('fa2cc213-f3b9-443f-a4b2-9a9bb743485b'), with its various components representing the SharePoint site (empty), list (GUID 953f306c-7b84-4e07-826c-a682779db88b) and file within the site.

This raw information is available within most API response objects in the raw->id attribute (not to be confused with raw->object, which contains all raw object metadata).

Overall, the flexibility with migrating between native upstream API requests that use raw IDs to Kloudless-managed API requests using unified IDs is immensely valuable to quickly scale to several integrations and build support deep, native functionality with each one.