Using "ETag" and the "If-Match" conditional header...

06-03-2025

Overview

In modern web applications, ensuring data consistency and preventing conflicts is essential, especially when multiple clients attempt to update the same resource concurrently. The ETag and If-Match HTTP headers offer a solution for these challenges. Here's how they work together to maintain data integrity.

ETag Response Header

An ETag (Entity Tag) is a unique identifier that the server assigns to a specific version of a resource. It is included in the response header when a client requests the resource. This identifier helps clients in managing cache and detecting resource changes.

Usage in API: When a client requests a resource, the server responds with the ETag value in the response header and as part of the response DTO (with the field name: "Timestamp").
Pagination Note: During paginated responses, the ETag value isn't included in the response header but is available within the response DTO (Field name: "Timestamp").

If-Match Request Header (Optional)

The If-Match HTTP header is used by clients to signal that they wish to update a resource only if its current version matches a specific ETag. This mechanism prevents resource conflicts when multiple clients try to update the same resource simultaneously.
See also, lost update problem, If-Match, HTTP conditional requests

Conflict Prevention: If the ETag stored on the server doesn't match the client's If-Match header, the server responds with a 412 Precondition Failed status code
Usage in API: Currently "If-Match" header is optional and can only be used with certain PUT & POST Action endpoints shared in detail in the following section below.

Example:

1) GET : .../api/v1/supplier/xxxxx
Response headers : ETag

Response body : timeStamp

2) PUT: .../api/v1/supplier/xxxxx
Request headers : If-Match

This request will succeed in updating the resource only if the resource's current "ETag" is "AAAAAE0YIiI=".

A) In case of success, the server returns "204 - No content" together with the new ETag value in the response headers.

B) In case of failure, the server returns "412 - Precondition Failed".

Advantages of using ETag and If-Match

Optimistic concurrency control: By using If-Match headers, clients can ensure that updates to resources are made safely without unwanted overwrites.
Data Integrity: Helps maintain data consistency by validating that resource updates are based on the most current data.

API Endpoints with ETag and If-Match Header Support

A) Endpoints & Operations Supporting "ETag" Response Header

GET, PUT & POST operations on the following endpoints include an "etag" in the response header:

Account
Budget
CashTransaction
Dimension
Employee
ExpenseClaim
JournalTransaction
PurchaseOrder
PurchaseOrderBasic
PurchaseReceipt
PurchaseReceiptBasic
Shipment
Subaccount
Supplier
SupplierInvoice
SupplierLocation
SupplierPayment
Timecard

Note: : "TimeStamp" field can also be checked via the DTOs where it's exposed.

B) Endpoints & Operations Supporting "If-Match" Request Header

PUT Account
PUT Budget
PUT CashTransaction
PUT Dimension
PUT Employee
PUT ExpenseClaim
PUT JournalTransaction
PUT PurchaseOrder
PUT PurchaseOrderBasic
PUT PurchaseReceipt
PUT PurchaseReceiptBasic
PUT Shipment
PUT Subaccount
PUT Supplier
PUT SupplierInvoice
PUT SupplierLocation
PUT SupplierPayment
PUT Timecard

If the endpoint is asynchronous,
meaning that if it is immediately returning a “202-Accepted” HTTP response and starts the actual job in the background, such as “Action” based operations. (Endpoint URL: …/action/…)
If-Match is supported in the following actions only with “erp-api-background usage,

POST SupplierPayment action/Release
POST SupplierInvoice action/Release
POST SupplierInvoice action/Prebook
POST SupplierInvoice action/voidinvoice
POST SupplierInvoice action/sendtoapproval

----------------------------------------------------------------------------------------------------------------------------------------

We're currently working on updating the swagger documentation, once the work is done, function will be listed on all the related operations / actions accordingly.

This knowledge article serves as a guide for developers to incorporate ETag and If-Match functionality into their applications, ensuring smooth updates and mitigating conflicts in a multi-client environment.