Merge-Update Endpoints

Merge-Update endpoints allow updates to only the fields specified in the request body. These endpoints use the POST HTTP method and conform to the JSON Merge Patch RFC.

Behavior

• Fields not included in the request body remain unchanged.
• Fields that cannot be modified:
  • Immutable fields are ignored if an update is attempted. For example, this applies to fields which can only be set upon creation.
  • In a future version of our API, attempts to modify these fields may result in an error unless the provided value matches the field’s current state, ensuring consistency and reducing the likelihood of mistakes.
  • Updating an immutable field to its existing value is always fine.

Refer to the endpoint-specific documentation for details on this behavior.

External References vs TandemDrive IDs

TandemDrive allows customers to use their own unique identifiers, referred to as external_reference, for nearly all stored records. For more information, see Identifiers.

Specifying a Unique Identifier

To update records via the update endpoints, you must provide a unique identifier in the path parameter. The behavior depends on whether the identifier is a TandemDrive ID or an external_reference.

Using a TandemDrive ID as the Path Parameter

• If the specified record does not exist, the update will fail, and no new record will be created.
• You can modify the external_reference of the record when using a TandemDrive ID as the path parameter.

Using an External Reference as the Path Parameter

• Use the prefix ext_ref. (including the dot) for the path parameter which supports using an external_reference.
• If the record does not exist, TandemDrive will create it automatically.
• When an external reference is used as the path parameter:
  • It overrides any external_reference specified in the request body.
  • The record will inherit the path parameter’s value as its external_reference.
  • It is not possible to update the external_reference to a different value.

Stale update prevention

To prevent clients from unintentionally overwriting data due to out-of-order API calls, several endpoints include an optional external_updated_at field in the request body, which is a date-time type.

Since external_updated_at can never be reset, there is an extra check that the field is never set to a date-time in the future. This prevents accidentally making a record immutable.

When an external_updated_at value (e.g., a) is provided, TandemDrive will compare it to the last stored external_updated_at value (e.g., b) for the corresponding record. The request will be processed only if a is more recent than or equal to b (a >= b).

The reponse from the Merge-Update endpoints will has a field operation which can have a value of "create" or "update". If the operation is an update then there is an additional field stale_update which specifies if the update was ignored because of an outdated external_updated_at value.