Optimistic locking

Preventing lost updates with version-based concurrency control

Navixy Repository API is a work in progress. This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.

Navixy Repository API uses the optional version field for optimistic concurrency control, preventing lost updates when multiple clients simultaneously edit the same entity.

How optimistic locking works

Every versioned entity includes a version field:

type Device {
  id: ID!
  version: Int!
  name: String!
  # ...
}

The version starts at 1 when an entity is created and increments with each successful update.

Update and delete mutations require the current version:

input UpdateDeviceInput {
  id: ID!
  version: Int!   # Optional parameter. Include to enable conflict detection.
  title: String
  # ...
}

input DeleteDeviceInput {
  id: ID!
  version: Int!   # Optional parameter. Include to enable conflict detection.
}

Supported entities

Optimistic locking applies to:

Entity	Description
Device	GPS trackers, sensors, beacons
Asset	Vehicles, equipment, employees
AssetGroup	Asset collections
Geo object	Geofences, POIs, routes
Schedule	Work hours, maintenance windows
Inventory	Warehouse records
Organization	Organization hierarchy nodes
User	User accounts
Member	Organization memberships
Integration	External system integrations
CatalogItem	All catalog items (device types, asset types, roles, tags, etc.)

Operations by type

Operation	Behavior
Create	Version not applicable. Returns version: 1
Update with version	Returns 409 Conflict if the entity was modified since your last fetch
Update without version	Applies unconditionally. Silently overwrites concurrent changes
Delete with version	Returns 409 Conflict if the entity was modified since your last fetch
Delete without version	Deletes unconditionally, regardless of any concurrent changes

Omitting version on a delete-type operation is particularly risky, as the operation proceeds unconditionally regardless of what happened to the entity since you last fetched it. Always include version when deleting unless you have a specific reason not to.

Workflow

Here's the typical flow for updating an entity:

1. Query returns version:

query {
  device(id: "550e8400-e29b-41d4-a716-446655440001") {
    id
    version    # Returns 5
    title
  }
}

1. Mutation requires version in input:

mutation {
  updateDevice(input: {
    id: "550e8400-e29b-41d4-a716-446655440001"
    version: 5          # Must match the current version
    title: "New name"
  }) {
    device {
      id
      version          # Returns 6 (incremented)
      title
    }
  }
}

Handling conflicts

If you provided version and the entity was modified since you fetched it, the API returns a 409 Conflict error. The HTTP status code will be 200 because the request was successfully received and processed — this is a business logic issue, not a transport failure. This follows the GraphQL-over-HTTP specification, which reserves HTTP error codes (4xx, 5xx) for transport-level problems like authentication failures or malformed requests.

The actual error details are in the response body:

{
  "errors": [{
    "message": "Conflict: entity was modified by another request",
    "path": ["deviceUpdate"],
    "extensions": {
      "type": "https://api.navixy.com/errors/conflict",
      "title": "Optimistic Lock Conflict",
      "status": 409,
      "detail": "Device was modified. Expected version 5, current version 6",
      "code": "CONFLICT",
      "entityType": "Device",
      "entityId": "550e8400-e29b-41d4-a716-446655440001",
      "expectedVersion": 5,
      "currentVersion": 6,
      "traceId": "2cf7651916cd43dd8448eb211c80319e"
    }
  }],
  "data": null
}

Use extensions.code for programmatic error handling, not HTTP status codes. See Error handling for more details.

When you receive a conflict error:

1. Fetch the entity again to see what changed

2. Merge the other user's changes with yours if needed

3. Retry your update with the new version

Concurrent editing example

Here's what happens when two users edit the same device:

User A's update succeeds first. User B's update fails because the version changed. After refetching, User B can successfully update with the current version.

Idempotent commands

Mutations that manage relationships and assignments are called idempotent commands. They don't require or check the version field.

Mutation	Purpose
deviceInventoryLink	Link device to inventory
deviceInventoryUnlink	Unlink device from inventory
deviceIdentifierAdd	Add identifier to device
deviceIdentifierRemove	Remove identifier from device
assetGroupItemsAdd	Add asset to group
assetGroupItemsRemove	Remove asset from group
roleAssign	Assign role to actor
roleRevoke	Revoke role from actor
permissionGrant	Grant permission to role
permissionRevoke	Revoke permission from role
userScopeSet	Set user scope restriction
userScopeRemove	Remove user scope restriction

These operations behave as follows:

• Calling link/assign/grant/add when the relationship already exists returns success without making changes

• Calling unlink/revoke/remove when the relationship doesn't exist returns success without making changes

This design simplifies client code. You can safely retry these operations without worrying about conflicts or checking the current state first.

Best practices

1. Always include version in your queries. When fetching entities you plan to modify, request the version field so you have it ready for mutations.

2. Always include version in updates and deletes. The field is optional, but omitting it removes your protection against overwriting changes made by other users since your last fetch. Omit it only for programmatic bulk operations where stale-read conflicts are not a concern.

3. Be especially careful when deleting without version. Unlike unprotected updates, which still write a valid version to the database, unprotected deletes can be irreversible.

4. Handle conflicts gracefully. In collaborative applications, version conflicts are expected. Implement retry logic or prompt users to review changes.

5. Don't cache versions long-term. Versions can change at any time. Always use the version from your most recent fetch of the entity.