Versioning & Concurrency

The Rekord API uses ETags and optimistic concurrency control to prevent lost updates when multiple clients modify the same resource.

ETags

Every mutable resource response includes an ETag header. The ETag is derived from a monotonic version counter — each mutation increments the version, providing a total ordering of changes.

HTTP/1.1 200 OK
ETag: "5"
Content-Type: application/json

{
  "modelId": "01957c3a-...",
  "name": "Applicant",
  "status": "active"
}

Conditional reads with If-None-Match

Use If-None-Match on GET requests to avoid re-fetching unchanged resources. If the resource has not changed, the server returns 304 Not Modified with no body:

curl "$REKORD_BASE_URL/models/01957c3a-..." \
  -H "Authorization: Bearer $REKORD_API_TOKEN" \
  -H "If-None-Match: \"5\""

Optimistic concurrency with If-Match

Use If-Match on write requests to prevent overwriting changes made by another client. The server compares the provided ETag against the current value and rejects stale writes:

curl -X PATCH "$REKORD_BASE_URL/models/01957c3a-..." \
  -H "Authorization: Bearer $REKORD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: \"5\"" \
  -d '{ "description": "Updated description" }'

If the resource has been modified since you last read it, the server returns 412 Precondition Failed:

{
  "error": {
    "status": 412,
    "code": "precondition_failed",
    "message": "Resource has been modified. Re-read and retry."
  }
}

Handling conflicts

When you receive a 412:

1. Re-read the resource to get the current state and ETag

2. Merge your changes with the current state

3. Retry the write with the new ETag

When If-Match is optional

If-Match is optional on all write requests — the server does not reject writes that omit it. However, without it, concurrent writes will silently overwrite each other. It is strongly recommended for:

• Model updates — where there is no other conflict resolution mechanism

• Rule updates — where accidental overwrites change decisioning logic

• Any resource edited by multiple users or systems

For records specifically, per-field resolution policies (highest confidence, most recent, etc.) provide an additional layer of conflict resolution for data arriving through contributions. But direct API writes arrive at the same confidence level — without If-Match, two users editing the same record directly will overwrite each other.

Version integer

The version integer is not included in the response body by default — the ETag header is the primary interface. If you need the integer for logging or debugging, request it via ?include=version:

{
  "modelId": "01957c3a-...",
  "name": "Applicant",
  "version": 5
}

Content integrity

Records carry a SHA-256 hash of their data object, returned as sha256 in the response. You can compare a locally held hash against the current value to detect changes without re-fetching the full record body. The hash is recomputed on every materialisation pass.

{
  "recordId": "01957c3a-...",
  "sha256": "a1b2c3d4e5f6...",
  "data": { ... }
}