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) take a unique value per logical operation (a UUID is
ideal).
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
200with 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:
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
versionincreases. - 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.
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 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 (with status and version)
so the workflow can check them.