Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Compatibility

RFC 1122/1123: “Adaptability to change must be designed into all levels of Internet host software.”

Our API follows a single versioning scheme. A new version is only introduced when major, backwards-incompatible changes are necessary. The API version is included in the URL path, so all paths in the specification are prefixed with /main/v1.

API and product versioning

  • API Version:

    The version number is part of the URL (e.g., /main/v1).

    To view the available API versions, use the /main/version endpoint. Note: This specific endpoint does not include the version prefix (/vN).

  • Product Version:

    To retrieve the current product version (distinct from the API version), check the X-TD-Version custom header in responses.

Versioning Notifications

TandemDrive will notify customers in advance when a new API version is planned. During transition periods, TandemDrive supports two concurrent API versions to ensure a smooth migration.

Backwards-compatible changes

A change is considered backwards-compatible if it does not break or require modifications to existing client implementations that conform to previous API releases. As the API evolves to support new features and services, we strive to maintain compatibility with previous releases. The following changes are considered backwards-compatible:

  • New resources: Adding new API endpoints.

  • Optional parameters: Introducing new optional request parameters to existing API methods.

  • Response properties: Adding new properties to existing API responses.

  • Enumerated fields: Extending predefined sets of values in enumerated fields. API clients should handle new values gracefully.

  • Property order: The order of properties in API responses is arbitrary and should not be relied upon.

  • String formatting: Changes in string formatting that don’t alter meaning (e.g., changes in case-insensitive identifiers or optional separators).

  • Human-readable messages: Modifying error messages or other human-readable strings.

  • Webhooks: Adding new event types. Your webhook listener should handle unfamiliar event types without failure.

  • Unused endpoints: Modifying endpoints that have not yet been used in production allows for iterative improvements based on feedback.

  • Required fields: Changing previously required parameters or fields to optional, as long as it doesn’t compromise the integrity or functionality of the API.

Preview endpoints

New features and endpoints in TandemDrive often start in preview mode, clearly marked as such in the API specification. See Preview mode for what the implications of using such features and endpoints are.

Handling breaking changes

While we prioritize backwards compatibility, there are rare occasions where breaking changes are required to enhance the API or introduce significant new features without warranting a full version change. In these cases, we take a customer-first approach to minimize disruption:

  1. Coordination and support: We work closely with each customer to coordinate the timing of the deployment, ensuring it aligns with their schedules and needs. Our team provides guidance and assistance to facilitate a smooth transition.

  2. Transition period: When possible, we provide a transition period where both the old and new versions are supported, allowing customers to gradually adapt to the changes without immediate impact.

  3. Testing and feedback: We encourage customers to test changes in their TandemDrive test instance before full deployment, and we remain open to feedback to address any concerns or issues that arise.

By taking this collaborative approach, we aim to ensure that breaking changes are handled as smoothly and efficiently as possible, minimizing impact on our customers’ operations.