Update Endpoints

TandemDrive provides two types of endpoints for performing updates:

1. Merge-Update Endpoints: These endpoints merge the provided values with existing field values using the POST HTTP method, enabling partial updates for greater flexibility and less room for mistakes.

2. Replace-Update Endpoints: These endpoints replace all field values in the target resource and use the PUT HTTP method. Since this approach can be challenging to implement correctly, we introduced the Merge-Update alternative for updating records.

   These endpoints replace all values for fields defined in the endpoint schema. Optional fields omitted from the request are reset to their default values, which is null unless otherwise specified.

   These endpoints are deprecated and should not be used for new implementations. A migration guide is provided for existing usage of these endpoints. TandemDrive plans to remove these endpoints once all customers have migrated to using the ‘Merge-Update’ alternative.

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.

Replace-Update Endpoints (deprecated)

Warning: Replace-Update endpoints are more challenging to use correctly. We highly recommend using Merge-Update endpoints for simpler and safer updates. We intend to remove the Replace-Update endpoints once they are no longer in use. A migration guide is provided for existing usage of these endpoints.

Replace-Update endpoints use the PUT HTTP method. According to the HTTP RFC on Idempotent Methods, PUT is idempotent, meaning repeated identical requests yield the same result.

A PUT request replaces all values for fields defined in the endpoint schema. Optional fields omitted from the request are reset to their default values, which is null unless otherwise specified.

Example Workflow:

To update only a subset of fields:

1. Use a GET request to retrieve the current values.
2. Modify the desired fields.
3. Submit the updated data via a PUT request.

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.