Skip to main content

SDK Versioning and Updates

Files.com SDKs use three-part version numbers. We ship new releases continuously. Files.com itself uses several of its own SDKs internally, so each release is exercised in production before it reaches you.

API Compatibility and Client Versions

Files.com intends to preserve API backward compatibility indefinitely and has a track record of maintaining it. We continue to support ExaVault API version 1.2, more than a decade after its introduction, for integrations carried forward from ExaVault.

The API version and the client version describe different things. The Files.com REST API uses the v1 API path. An SDK, CLI App, or Terraform provider has its own release number; a new SDK major version does not mean the service has moved to a new API version. An SDK release can change language-level interfaces even while the underlying API remains compatible.

Files.com updates the hosted service automatically. Pinning a client dependency controls the library deployed with your application; it does not freeze the service or its features. Review client releases through their repository and package channel, and What's New for product changes.

Files.com SDK Versioning

Files.com SDKs follow a three-part versioning system in the form of MAJOR.MINOR.BUILDNUMBER, producing version numbers such as 1.4.221 or 1.3.0.

In conventional semantic versioning, a major release can contain incompatible changes, a minor release adds compatible functionality, and a patch release contains compatible fixes. Files.com's SDK numbering differs in its minor and build releases.

Updates within a major version are generally backward compatible, but some minor-version changes can require changes to your application. MAJOR or MINOR changes may introduce breaking changes, so review the changes whenever either number differs from the version you have deployed.

Changes to the BUILDNUMBER reflect bug fixes, performance improvements, or new functionality that does not introduce breaking changes. Updating the SDK when only the BUILDNUMBER has changed is generally not disruptive.

Use the Most Current SDK Version

Use the most current version of the Files.com SDK in your projects. When you contact our support team for help with your code, this is always the first suggested troubleshooting step, because improvements and fixes to the SDKs are released continuously.

Files.com does not issue separate, real-time announcements for SDK security updates. Review releases through the official GitHub repositories and package channels and keep the dependency current rather than waiting for an individual security advisory.

Review the runtime and dependency requirements in the selected SDK's developer reference or README. Files.com does not support frameworks or dependencies that have reached end of life; updating an SDK may also require updating the runtime that runs your application.

Identifying Differences Between SDK Versions

Each SDK is released on GitHub along with the appropriate package managers. Releases are tagged with version numbers. GitHub's compare feature lets you review the differences between two versions to determine whether any parts of an SDK you use have changed. This helps you track modifications, assess risk, and decide whether an upgrade is necessary for your use case.

The URL for comparing two versions of an SDK is:

https://github.com/Files-com/<SDK>/compare/<OLD VERSION>...<NEW VERSION>

Replace <SDK> with the appropriate repository name for your SDK, one of: files-sdk-dotnet, files-sdk-go, files-sdk-java, files-sdk-javascript, files-sdk-php, files-sdk-python, or files-sdk-ruby.

Replace <OLD VERSION> with the tag matching your current version of the SDK, and <NEW VERSION> with the tag matching the release you want to move to.

For example, to compare the Python SDK from version 1.4.99 to 1.4.222, the final URL is:

https://github.com/Files-com/files-sdk-python/compare/v1.4.99...v1.4.222External LinkThis link leads to an external website and will open in a new tab

Best Practices for SDK Upgrades

New versions of the official Files.com SDKs are published regularly, and bring better performance and access to new features. Recent versions also make support interactions easier and give you the full benefit of the SDK.

The practices below balance the benefits of staying current with the confidence that your critical bespoke code will continue working.

Manage Changes With Pinned SDK Versions

Pinning the versions of dependencies your code uses (including the Files.com SDKs) prevents updates from being applied automatically. This keeps unexpected changes out of production and gives you full control over when to introduce new versions.

The method for pinning varies by language. For most customers, we recommend pinning the minor version. For example, this allows an SDK to update automatically from version 1.2.3 to 1.2.4, but not from 1.2.3 to 1.3.0.

Pinning controls when a release enters your application; it does not keep the pinned version updated with fixes released in newer versions. Review new minor and major releases regularly, test the required changes, and update the pin as you deploy them.

When an SDK is published with a new major or minor version, compare the differences to identify whether the new version requires any changes to your code.

Testing SDK Updates in a Staging Environment

If you rely on a custom solution built on a Files.com SDK for an important workflow, maintain a separate testing or staging environment. This lets you verify that your code (and the dependencies of your code) will continue to work when changes are made. Depending on what your custom code does, a staging environment might connect to your main Files.com site or to a separate child site.

A staging workflow helps you identify compatibility issues or breaking changes before rolling out updates to live systems.