Data update guarantees

Strong consistency

Each resource provides read-after-write consistency for the same entity endpoint. This ensures that when an entity is updated, the changes are immediately available after a successful response when you query the same endpoint for that entity.

REST API

Example: If you update the facility details via POST /api/facilities/{ID} and wait for the response, a subsequent read GET /api/facilities/{ID} will immediately reflect the updated state. However, a read of all facilities using GET /api/facilities/ does not guarantee that the updated facility's details will be instantly reflected, as list views or aggregated views on data may rely on eventual consistency. This restriction explicitly includes reads with specific filters or pagination parameters.

GraphQL API

Example: In our GraphQL API, read-after-write consistency is guaranteed for root-level fields when querying an entity by its ID. For instance, if you update a facility's details using a mutation:

mutation {
  updateFacility(input: { id: "123", ... }) { ... }
}

A subsequent query for the same facility will immediately reflect the updated state:

query {
  facilityV2(id: "123") { ... }
}

However, a query for all facilities does not guarantee that the updated facility's details will be instantly reflected, as list views or aggregated views on data may rely on eventual consistency. This restriction explicitly includes reads with specific filters or pagination parameters.

Eventual consistency

After an update, some updates are not immediately visible in the used clients (especially mobile and web clients). For example, if a shipment was created, which is, by design, an asynchronous process, updating the shipment itself provides read-after-write consistency, but the platform delays updating the actual visibility in said clients. Additionally, we guarantee eventual consistency for any list views on our data, e.g., a list of facilities.

These delayed updates provide an eventual consistency guarantee. This means that you can see the changes you or a follow-up process performed after a delay. These delays can vary depending on the amount of data to update. We try to keep these delays as small as possible.

Optimistic concurrency control (optimistic locking)

Many API resources use optimistic concurrency control to prevent lost updates when concurrently changing existing data. These resources have a version attribute. When sending updates to these resources, the expected (and to the client's last known version) of a resource is sent as a part of the request. After updating, the HTTP response body contains the new version of the resource.

Background processes and other events can also change a resource’s version number without any requests sent from an API client directly to the resource. Do not rely on a consistently incremented version number.

The API does not use ETag and If-Match HTTP headers to control optimistic concurrency. The API returns a 409 HTTP status (Conflict) error if a version mismatch occurs.