ETag and If-Match Headers

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.

Refer to 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, the “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: …/v1/supplier/xxxxx

Response headers: ETag

ETag

Response body: timeStamp

TimeStamp

2. PUT: …/v1/supplier/xxxxx

Request headers: If-Match

Header

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.

ETag2

B. In case of failure, the server returns “412 - Precondition Failed”.

Message

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

Endpoints & Operations Supporting “ETag” Response Header

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

Account
Budget
CashSale
CashTransaction
Contact
Customer
CustomerCreditWriteOff
CustomerDebitNote
CustomerInvoice
CustomerOverdueCharge
CustomerPayment
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.

Endpoints & Operations Supporting “If-Match” Request Header

PUT Account
PUT Budget
PUT CashTransaction
PUT CashSale
PUT Contact
PUT Customer
PUT CustomerDebitNote
PUT CustomerInvoice
PUT CustomerOverdueCharge
PUT CustomerPayment
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 immediately returns 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 CustomerDebitNote action/Release
POST CustomerDebitNote action/sendToAutoInvoice
POST CustomerOverdueCharge action/release
POST CustomerPayment action/Release
POST CustomerPayment action/Void
POST SupplierPayment action/Release
POST SupplierInvoice action/Release
POST SupplierInvoice action/Prebook
POST SupplierInvoice action/voidinvoice
POST SupplierInvoice action/sendtoapproval