Knowledge base in Developers Visma.net

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.