Migration Guide: Transitioning from Replace-Update to Merge-Update

TandemDrive is streamlining its API by replacing the “Replace-Update” mechanism with a more robust and user-friendly “Merge-Update” approach. The “Replace-Update” method, while functional, presents complexities in implementation and potential for unintended data loss.

Action Required: Migrate to Merge-Update Endpoints

We strongly encourage all customers to transition from the existing “Replace-Update” endpoints to the new “Merge-Update” equivalents. In many cases, the migration is as simple as changing HTTP PUT requests to POST requests.

Key Change: Handling Unspecified Fields

The primary difference lies in how unspecified fields are handled. Under “Replace-Update,” omitted fields were often reset to their default values (typically null). This behaviour was documented but this is easily missed, and it’s challenging to implement correctly. With “Merge-Update,” only the fields explicitly included in the request are modified. Existing data in unmentioned fields remains unchanged.

Simplifying Specialized Endpoints

We’ve also consolidated several specialized endpoints that targeted single or small sets of fields. These are now superseded by the more versatile “Merge-Update” endpoints. To achieve the same functionality, simply include only the desired fields in your POST request.

The endpoints mentioned in the two lists below will be removed, once everyone has migrated to the “Merge-Update” endpoints.

“Replace-Update” endpoints

The endpoints in the list below use the “Replace-Update” approach. In most cases you can switch to the “Merge-Update” approach by replacing PUT with POST:

• PUT /main/v1/customer/{id}

• PUT /main/v1/billing-address/{id}

• PUT /main/v1/billing-direct-debit-mandate/{id}

• PUT /main/v1/cpo-reimbursement-arrangement/{id}

• PUT /main/v1/cpo-reimbursement-link/{id}

• PUT /main/v1/cpo-subscription/{id}

• PUT /main/v1/cpo-subscription-evse-link/{id}

• PUT /main/v1/msp-token/{evco_id}

• PUT /main/v1/msp-token-subscription/{id}

• PUT /main/v1/msp-token-link/{id}

• PUT /main/v1/end-user/{id}

• PUT /main/v1/end-user/{id}/authorization-customer becomes POST /main/v1/end-user/{id}/authorization-customer/{customer_id}

• PUT /main/v1/end-user/{id}/authorization-msp-token-subscription becomes POST /main/v1/end-user/{id}/authorization-msp-token-subscription/{subscription_id}

Endpoints which are no longer necessary

The endpoints below were designed to update only a single field, or a select set of fields. This can now be achieved with our “Merge-Update” endpoints by only mentioning the fields that should be updated. The DELETE variants of the endpoints below can be replaced by explicitly setting a field to the null value.

• PUT /main/v1/cpo-reimbursement-arrangement/{id}/valid-from

• PUT /main/v1/cpo-reimbursement-arrangement/{id}/valid-until

• DELETE /main/v1/cpo-reimbursement-arrangement/{id}/valid-until

• PUT /main/v1/cpo-reimbursement-link/{id}/valid-from

• PUT /main/v1/cpo-reimbursement-link/{id}/valid-until

• DELETE /main/v1/cpo-reimbursement-link/{id}/valid-until

• DELETE /main/v1/cpo-reimbursement-link/{id}/valid-from

• PUT /main/v1/cpo-subscription/{id}/valid-until

• PUT /main/v1/cpo-subscription/{id}/valid-from

• DELETE /main/v1/cpo-subscription/{id}/valid-until

• PUT /main/v1/cpo-subscription-evse-link/{id}/valid-until

• PUT /main/v1/cpo-subscription-evse-link/{id}/valid-from

• DELETE /main/v1/cpo-subscription-evse-link/{id}/valid-until

• DELETE /main/v1/cpo-subscription-evse-link/{id}/valid-from

• PUT /main/v1/msp-token-subscription/{id}/valid-from

• PUT /main/v1/msp-token-subscription/{id}/valid-until

• DELETE /main/v1/msp-token-subscription/{id}/valid-until

• PUT /main/v1/msp-token-link/{id}/valid-until

• PUT /main/v1/msp-token-link/{id}/valid-from

• DELETE /main/v1/msp-token-link/{id}/valid-until

• DELETE /main/v1/msp-token-link/{id}/valid-from