UXPROD-1752 for an overview.
So far we have discussed a couple of different options for the protocol:
1. use ETag response header with If-Match conditional request. Respond with 412 Precondition Failed on collision detection
- Pros: standard HTTP feature for OL, supported by browsers, easy to implement – no API changes in FOLIO besides new error code
- Cons: works on resource-level so handling individual records during batch updates (collections) is not supported
2. put the "etag" in the entity schema (body). Client repeats server-provided value. Respond with 409 Conflict on collision detection.
- Pros: solves the problem with updating individual records during batch updates
- Cons: non-standard, requires changes to entity schemas
ETags can be either "strong" (byte-for-byte similarity) or "weak" (semantic similarity).
Etags can be generated as hashes/checksums, as a revision number or as a date.
Option 2 may work similar to how metadata.schema works. Though can't use the metada.schema itself because it's marked readonly when used.
Option 2 may not be immediately useful as FOLIO does not support partial batch updates anyway.
We need to decide if the OL functionality is optional or required: e.g in Option 1 always fail with 412 Precondition Failed when no If-Match supplied, in Option 2 require the etag field.
We need to decide how we support batch updates. Quote from
UXPROD-1752: "This situation can happen when multiple data imports are happening at the same time (or data import and a user acting on the same record at the same time) and can affect many records at the same time.")
Update examples if "version" property is optional
old is the value stored in the module/database, req is the record of the API request, new is the value stored in the module/database after the request
Missing "version" property is treated as if it were "version": 0.
Update examples if "version" property is required