How to use the unified file storage API

December 25, 2023

The new File Storage unified API allows your application to traverse your customer's folders and files on their favourite cloud storage provider, much like a OS's file manager. These cloud storage providers include Google Drive, Microsoft OneDrive, Microsoft SharePoint, Dropbox, Box, and Amazon AWS S3.

StorageFile object

There is only one object that is returned and it represents both a file or a folder. A folder has type set to FOLDER and will not have a size nor download_url value.

type StorageFile = {
    id?: string;
    created_at?: string; // ISO date
    updated_at?: string; // ISO date
    name?: string;
    description?: string;
    parent_id?: string;
    user_id?: string;
    size?: number;
    type?: 'FILE' | 'FOLDER';
    mime_type?: string;
    permissions?: {
        user_id?: string;
        group_id?: string;
        roles?: any;
    }[];
    download_url?: string;
}

Listing the contents of a folder

To list the contents of a folder, call the listFiles API endpoint. When called without a parent_id, the root level folder is returned. This root level can be different for different cloud storage providers and could be drives, sites, or folders.

To traverse the file system and get the contents of subfolders just include the parent_id of a folder when calling listFiles. A parent_id can only reference a folder and not a file.

import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: {
        jwt: '<YOUR_API_KEY_HERE>',
    },
});

export async function getFolder(connectionId: string, parentId?: string) {
    // get contents of folder

    const result = await sdk.storage.listStorageFiles({
        parentId,
        connectionId,
    });

    return result.storageFiles;
}

// get root foldet
// getFolder(connection_id);

// get a subfolder
// getFolder(connection_id, folder_id)

Retrieve the contents of a file

If you want to get the data contents of a file, either use the getFile API endpoint or take a File object from the listFiles API endpoint. Use the download_url field to fetch the contents of that file. How you fetch that data will be dependent on your programming language.

For example, here is a code snippet to retrieve the contents of a file:

import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: {
        jwt: '<YOUR_API_KEY_HERE>',
    },
});

export async function getFileContents(connectionId: string, id: string) {
    // get file details
    const result = await sdk.storage.getStorageFile({
        id,
        connectionId,
    });

    if (!result.storageFile) {
        throw new Error('file not found');
    }

    if (!result.storageFile.downloadUrl) {
        throw new Error('not a downloadable file');
    }

    // Get the data contents of a file
    const contents = fetch(result.storageFile.downloadUrl, { Accept: result.storageFile.mimeType });

    return contents;
}

References

Blog