ConnectCloud Developers

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 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:

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.
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.

View as Markdown