Best Practices for Integrating with Files.com

The Files.com platform provides built-in capabilities to connect to external systems, including built-in connectors to external storage solutions, identity solutions, and notification services. The platform also provides built-in workflow tasks, such as Automations, Syncs, and Folder Settings, that can be used to automate encryption and data movement between systems. We also provide multiple ways for you to integrate with us.

We have SDKs, RESTful APIs, and a Command Line Integration (CLI) App available for use. Each of these provides different methods for integration, allowing you to choose the methods that best fit your needs.

We also have customers who use iPaaS platforms, such as Microsoft Power Automate, Azure Logic Apps, Boomi, Zapier and MuleSoft, to integrate with Files.com using official connectors from those platforms.

This guide explains how to choose the most appropriate integration method and how to build reliable integrations with Files.com.

Most integrations fall into one of two categories:

• Integrations that move files
• Integrations that interact with the Files.com platform

Understanding which category applies to your integration will help determine the correct integration method.

Identify the Type of Integration

Before selecting an integration method, determine what your integration must accomplish. Most integrations either move files between systems or interact directly with the Files.com platform to manage configuration or operational data.

Integrations That Move Files

Many integrations exist primarily to move files between Files.com and other systems.

Examples include:

• Uploading or downloading files from an application
• Automating partner file exchanges
• Collecting files through an Inbox or inbound Share Link
• Distributing files through Share Links
• Moving files between storage systems

Some integrations only transfer files. Other integrations must also control what happens to files after they arrive on Files.com. For example, an application may upload a file and then rename it, move it to another folder, create a Share Link, or trigger additional processing.

Several integration methods support these scenarios depending on the environment where the integration runs.

Use a Files.com SDK for applications written in a programming language that Files.com supports. The SDK provides a developer-friendly interface that simplifies authentication, request formatting, error handling, and retries. When using an iPaaS platform, use our corresponding iPaaS connector.

Use the Files.com CLI app for Script-based automation environments. Command-line environments that use shell scripts, PowerShell scripts, and CI/CD pipelines can invoke the CLI app directly without requiring custom API client implementations.

Integrate using the REST API for applications written in languages where a Files.com SDK isn't available. API integrations work from any environment but require the application to handle authentication, request formatting, retries, and error handling.

Some systems cannot run custom application code or API integrations. Legacy systems, partner platforms, and third-party tools often rely on traditional file-transfer interfaces. For these environments, integrate using SFTP, FTPS, FTP, or, as a last resort, WebDAV.

Integrations That Interact With the Files.com Platform

Other integrations interact with Files.com as a platform rather than using it only as a file transfer endpoint.

Examples include:

• Provisioning or managing users
• Managing folder permissions
• Retrieving logs or audit records
• Automating administrative tasks
• Managing site configuration
• Performing operational reporting

These integrations require direct interaction with the Files.com platform rather than simple file transfer interfaces.

Use a Files.com SDK for applications written in supported programming languages because it exposes the full capabilities of the platform through a developer-friendly interface. When using an iPaaS platform, use our corresponding iPaaS connector.

Use the Files.com CLI app for operational automation environments that implement administrative scripts or CI/CD pipelines. The CLI app allows scripts to perform repeatable administrative tasks without requiring custom API client code.

Use Terraform for infrastructure and configuration automation workflows. Terraform allows administrators to define Files.com configuration as code and manage that configuration using infrastructure-as-code practices.

Interact with Files.com through the REST API when using applications written in languages where an SDK is not available.

File transfer protocols (FTPS, SFTP or WebDAV) are not appropriate for administrative integrations because those protocols only provide file access and do not expose platform management capabilities.

Integration Method Decision Guide

Start by identifying what your integration needs to accomplish.

Move Files

Use these approaches when your integration transfers files between Files.com and other systems.

• Application written in a supported programming language: Use a Files.com SDK.
• Shell scripts, PowerShell scripts, CI/CD pipelines, or automation scripts: Use the Files.com CLI app.
• Application written in a language without a Files.com SDK: Use the REST API.
• External system only supports file-transfer interfaces: Use SFTP, FTPS, or WebDAV.

Interact With the Files.com Platform

Use these approaches when your integration manages the Files.com platform itself.

Examples include user provisioning, retrieving logs, managing permissions, and automating administrative tasks.

• Application written in a supported programming language: Use the Files.com SDK.
• Operational automation or scripting environments: Use a Files.com CLI app.
• Infrastructure or configuration automation: Use Terraform.
• Application written in a language without a Files.com SDK: Use the REST API.

Additional Method Details

The following sections describe each integration method and the environments where developers typically use them.

SDKs

We provide SDKs for 7 programming languages; Go, Java, JavaScript, Microsoft .NET, PHP, Python, and Ruby.

An SDK is our most recommended choice for customers working with any of the supported programming languages.

Our SDKs use our secure APIs and include developer-friendly features such as built-in automatic retries, fast performance, automatic pagination handling, and automatic transfer chunking where available. The SDKs provide you with the tightest integration between our APIs and your programming language of choice.

We have invested time into optimizing file operations, including parallelization of uploads and downloads, in some SDKs.

As we add new platform features, our SDKs are automatically updated and optimized to support those features.

iPaaS Connectors

We provide iPaaS connectors for Microsoft Power Automate, Azure Logic Apps, Boomi, Mulesoft, and Zapier.

These official connectors are recommended for customers who have implemented these iPaaS platforms for their business processes, or for organizations that embrace no-code or low-code integration approaches that allow business users and technical teams to automate workflows without developing custom code.

The Boomi, Mulesoft, and Zapier connectors use our SDKs and inherit their built-in features including automatic retries, fast performance, automatic pagination handling, and automatic transfer chunking where available.

The Power Automate and Logic Apps connector uses our official secure APIs to optimize file transfers between Files.com and your business workflows.

CLI

The Command Line Integration (CLI) App is cross-platform and available for Windows, Linux, and Mac.

The Command Line Integration (CLI) App is our most recommended choice for customers requiring integration from a scripting language such as PowerShell, shell scripts (bash, csh, zsh, etc.), and DOS batch files (BAT).

The Command Line Integration (CLI) App uses our secure APIs and provides built-in automatic retries, fast performance, automatic pagination handling, and automatic transfer chunking. Use the CLI App for the tightest integration between our APIs and your scripting language of choice.

Output format can be specified (JSON, CSV, or table) for easier post-processing within your script.

As we add new platform features, the CLI App is automatically updated and optimized to support those features.

Terraform

Terraform provides Infrastructure-as-Code (IaC) management for Files.com administrative resources. It enables versioned configuration, repeatable deployments, and safer automation across environments.

Terraform users define and configure data center infrastructure using a declarative configuration language known as Terraform Configuration Language, or optionally JSON.

The Files.com Provider for Terraform allows you to automate the management of your Files.com site, including resources representing users, groups, folders, share links, inboxes, automations, security, encryption, access protocols, permissions, remote servers, remote syncs, data governance, and more.

Use Terraform if you have implemented infrastructure-as-code practices at your organization.

APIs

We provide RESTful web service APIs. These can be invoked from any HTTP client, including those contained within any programming language, programming script, or iPaaS platform.

The APIs are our recommended choice for customers requiring integration from a system which cannot use our SDKs or CLI App.

Using these "raw" APIs provide you with micro services which you'll need to build your own additional logic around to handle response outcomes, retries, and for exception handling.

As we add new platform features, the APIs are automatically updated to support those features.

Protocols

Our platform provides support for file transfer protocols, including FTP(S), SFTP, and WebDAV. These protocols provide the ability to upload, download, move, copy, rename, and delete files and folders. These file and folder actions can be programmatically executed from batch command scripts for the protocol or from external scripts.

The protocols are our recommended choice for customers who need to transfer files and folders from a system that cannot use our SDKs, CLI App, or APIs, such as from embedded systems with built-in file transfer protocol support.

The protocols are our least recommended choice for performing programmatic move, copy, and rename operations.

These protocols were designed prior to cloud based platforms and assume that all operations are executed synchronously. They are unaware of asynchronous background operations and cannot provide accurate responses about the current state of a file or folder that has an asynchronous operation being performed on it.

Asynchronous Background Operations

The Files.com platform performs some operations asynchronously and these operations will run in the background in parallel.

Whenever you programmatically integrate with Files.com, such as from a script or iPaaS process, account for asynchronous operations because some platform actions trigger background processing and your integration must handle the fact that the requested change may not be immediately visible or complete.

For example, moving a file from one Files.com storage region to another, or from one Remote Server Mount to another, will asynchronously create a background process to move the file. Control is immediately returned even though the move is still occurring in the background.

Our SDKs, CLI App, and APIs will provide responses that indicate when an asynchronous operation occurs and provides methods which you can use to query the current status, and final outcome, of an asynchronous operation.

Integrating via a protocol will not provide any indication about whether an operation is asynchronous. Make sure to implement checks and validations in your script, or process, to verify that an operation has completed prior to any further processing steps.

Retries

Our SDKs and CLI App include built-in retry logic, which automatically repeats a request when a temporary network interruption or server-side condition prevents the request from completing successfully. This retry behavior allows integrations to recover from transient failures without requiring additional error-handling code. Some protocol clients provide built-in retries for uploads and downloads but this is typically implemented for interactive user sessions rather than for programmatic scripts.

Our SDKs, CLI App, and APIs will provide responses that indicate if an action fails which you can use in your programs, scripts, and processes to trigger your own retry logic.

Protocol clients may, or may not, provide exits codes that indicate the outcome of batch commands.

Bear in mind that too many retries, performed too quickly, will look like a cyberattack to network security devices. We recommend retry logic that introduces increasing durations between retry attempts.

Parallelism

The Files.com platform, as a Software-as-a-Service (SaaS) cloud-based solution, provides elastic scalability which allows for a practically unlimited number of parallel connections.

When using parallel threads or processes to interact with Files.com, take into consideration that operations may be asynchronous and that other processes, or users, may be interacting with files and folders at the same time.

Performance Considerations

Operations

Operations performed on the Files.com platform will take an identical amount of time no matter how the operation was triggered.

For example, moving a file from one folder to another will take the same amount of time no matter whether the copy operation was started via SDK, API, CLI App, Automation, Folder Setting, FTP, SFTP, WebDAV, or web portal.

There are caveats to the above example. Some protocol clients, for example, will "copy" a file by downloading it from its source folder and re-uploading it to its destination folder. In these kinds of scenario, the operation will take longer due to the round-trip route from server to client and back again.

Moves and copies from one Files.com storage region to another, or from one Remote Server Mount to another, will always take longer than an identical operation whose source and destination reside within the same storage region or storage location.

Uploads and Downloads

For uploads and downloads, the fastest transfer method is via HTTPS using our SDKs, CLI App, APIs, and web portal.

Our SDKs, CLI App, and web portal will automatically apply parallelism and chunking to transfers to give you the best possible transfer performance.

When using our APIs, your application, program, or script will need to manage any parallelism and chunking.

Protocol based transfers are slower due to the underlying protocol itself. Various factors affect the transmission speed of a protocol including its encryption methods and how "chatty" it is. A chatty protocol is one that requires a lot of back-and-forth acknowledgement to be sent between the client and the server. For example, even though WebDAV uses the HTTPS protocol, it is a very chatty protocol and is very affected by network latency.

Traditionally, on-premise SFTP has been a slower transmission protocol than FTP(S), due to its encryption methods and its use of a single data transmission port. However, cloud based SFTP benefits from SaaS elasticity and is often faster than FTP(S).

WebDAV is a convenient connection protocol for desktop users, as it's built into almost every Windows, Mac, and Linux desktop, but only performs well over a local area network (LAN). Over the internet, WebDAV is a slow transmission protocol due to its network chattiness.

Whenever there are multiple possible file transfer options available, we recommend the following order for transfer speeds, from fastest to slowest:

1. SDKs, CLI App, APIs, or web portal
2. SFTP or FTP(S)
3. WebDAV

Calculating Folder Size

The SDKs and API provided by Files.com don't provide a method to recursively calculate the size of a folder tree. This is because any folder within your site could contain Remote Server Mounts. Some Remote Server types can't provide the size of a folder tree performantly, or even at all.

Anything you build with our SDKs will work the same, regardless of where your files happen to be stored. To fulfill that promise, we do not provide a recursive size function.

Assistance

We're developer-friendly and here to help. Please feel free to contact us with any questions.

Our Customer Support team is available to assist you with guidance and recommendations on the best ways to integrate your business processes with Files.com.