> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/optimistic-locking.md). # Optimistic locking Preventing lost updates with version-based concurrency control {% hint style="warning" %} **Navixy GraphQL 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. {% endhint %} The 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: ```graphql 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 accept the current version: ```graphql input DeviceUpdateInput { id: ID! version: Int # Optional. Include to enable conflict detection. title: String # ... } input DeviceDeleteInput { id: ID! version: Int # Optional. Include to enable conflict detection. } ``` ## Supported entities Optimistic locking applies to:
EntityDescription
DeviceGPS trackers, sensors, beacons
AssetVehicles, equipment, employees
AssetGroupAsset collections
Geo objectGeofences, POIs, routes
ScheduleWork hours, maintenance windows
InventoryWarehouse records
WorkspaceTenants. Read-only in this API, so the version is informational
UserUser accounts
MemberWorkspace memberships
IntegrationExternal system integrations
CatalogItemAll catalog items (device types, asset types, tags, etc.)
## Operations by type
OperationBehavior
CreateVersion not applicable. Returns version: 1
Update with versionReturns 409 Conflict if the entity was modified since your last fetch
Update without versionApplies unconditionally. Silently overwrites concurrent changes
Delete with versionReturns 409 Conflict if the entity was modified since your last fetch
Delete without versionDeletes unconditionally, regardless of any concurrent changes
{% hint style="warning" %} 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. {% endhint %} ## Workflow Here's the typical flow for updating an entity: 1. Query returns version: ```graphql query { bdr { device(id: "550e8400-e29b-41d4-a716-446655440001") { id version # Returns 5 title } } } ``` 2. Mutation includes the version in its input: ```graphql mutation { bdr { deviceUpdate(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](/docs/navixy-graphql-api/error-handling.md#version-conflict-409) 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](https://graphql.github.io/graphql-over-http/draft/), 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: ```json { "errors": [{ "message": "Conflict: entity was modified by another request", "path": ["bdr", "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](/docs/navixy-graphql-api/error-handling.md) 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: repeating the same call doesn't change the result. They don't require or check the `version` field.
MutationPurpose
assetGroupItemsAddAdd asset to group
assetGroupItemsRemoveRemove asset from group
These operations behave as follows: * Repeating `add` with the same input returns success without making changes * Calling `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. {% hint style="warning" %} The device link and identifier mutations are **not** idempotent: * `deviceInventoryLink` fails when the device is already assigned anywhere, and `deviceInventoryUnlink` fails when it has no active assignment. See [Managing device inventory](/docs/navixy-graphql-api/business-data-repository/guides/managing-device-inventory.md). * `deviceIdentifierAdd` returns a [409 DUPLICATE](/docs/navixy-graphql-api/error-handling.md#duplicate-409) error when the identifier already exists, on this or any other device, and `deviceIdentifierRemove` returns a [404 error](/docs/navixy-graphql-api/error-handling.md#entity-not-found-404) for an unknown or already-removed identifier ID. {% endhint %} ## 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 bulk operations where overwriting concurrent changes is acceptable. 3. Be especially careful when deleting without `version`. A wrong update can usually be corrected with another update, but a delete without `version` can permanently remove an entity that another user just changed. 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. ## See also * [Error handling](/docs/navixy-graphql-api/error-handling.md): Understand error structure, codes, and common error scenarios * [Managing device inventory](/docs/navixy-graphql-api/business-data-repository/guides/managing-device-inventory.md): Assign devices to inventories and track assignment history --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-graphql-api/optimistic-locking.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.