# Idempotency and concurrency

## Idempotent creates

Networks fail. If a `POST` times out you cannot know whether it was processed. Endpoints that
create resources and list an `Idempotency-Key` header parameter in the reference (for example
[`POST /items`](/reference/desk/createItem)) take a unique value per logical operation (a UUID is
ideal).

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6c1f0a52-0d0e-4a43-9c55-8f6e1f2a0b7d' \
  --data '{"spaceId": "SUP", "title": "VPN-Verbindung bricht ab"}'
```

- The first request creates the item and answers `201`.
- Any repetition with the same key within **7 days** answers `200` with the item created first,
  even if the body differs.
- Use a new key for every new item, and the same key for every retry of the same item.

Desk items additionally accept a `dedupeKey` field: an identifier from *your* system (for example
`monitoring:alert:8812`). As long as an item with that key exists, creating another one returns the
existing item. Use it when the same event can reach you twice, e.g. from a monitoring system.

## Optimistic locking

Resources that can be edited concurrently carry an integer `version`. To change them, send the
`version` you read:

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/desk/v1/items/1234' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"version": 7, "priority": "hoch"}'
```

- If nobody changed the item since you read it, the change is applied and `version` increases.
- If somebody else changed it first, the API answers `409 {"code": "version_conflict"}` and
  changes nothing. Read the resource again, re-apply your change and retry.

```text
GET  item ─► version 7
PATCH {version: 7} ─► 200, version 8      (you win)
PATCH {version: 7} ─► 409 version_conflict (someone else won: GET again)
```

Desk also accepts the version as `If-Match` header instead of the body field. People and
integrations (a session, an API key, an OAuth client, the assistant) must send the version when
they update a desk item or change its status: without one the API answers
`400 {"code": "invalid", "field": "version"}` and changes nothing. Only automations – a
[flow](/guides/flows) or a desk automation, which act on an event without reading the item first –
may leave it out; their change then applies to the item as it is (last write wins). A version an
automation does send is checked like everyone else's.

## Partial updates

`PATCH` endpoints apply only the keys you send; `null` clears a value; keys you leave out stay
unchanged. `PUT` endpoints replace the whole resource. Status changes of desk items go through
[`POST /items/{ref}/transition`](/reference/desk/transitionItem) (with `status` and `version`)
so the workflow can check them.
