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

ℹ️ PUT: The ETag of the recently updated entity is included in the response header.

ℹ️ POST: The ETag of the recently created entity is included in the response header.

GET Supplier
PUT Supplier
POST Supplier
GET SupplierInvoice
PUT SupplierInvoice
POST SupplierInvoice
GET SupplierLocation
PUT SupplierLocation
POST SupplierLocation
GET SupplierPayment
PUT SupplierPayment
POST SupplierPayment
GET Shipment
PUT Shipment
POST Shipment
GET PurchaseOrder
PUT PurchaseOrder
POST PurchaseOrder
GET PurchaseOrderBasic
PUT PurchaseOrderBasic
POST PurchaseOrderBasic
GET PurchaseReceipt
PUT PurchaseReceipt
POST PurchaseReceipt
GET PurchaseReceiptBasic
PUT PurchaseReceiptBasic
POST PurchaseReceiptBasic

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

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

PUT Supplier
PUT SupplierInvoice
PUT SupplierLocation
PUT SupplierPayment
PUT Shipment
PUT PurchaseOrder
PUT PurchaseOrderBasic
PUT PurchaseReceipt
PurchaseReceiptBasic

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.