Idempotency and ETags

What this is: two headers that make retries and concurrent edits safe. When you need it: any create you might retry; any update someone else might race.

curl

# read, keep the ETag
etag=$(curl -sI "$TASKSMATE_API_URL/v1/tasks/T123456" -H "Authorization: Bearer $TASKSMATE_TOKEN" \
  | awk -F': ' 'tolower($1)=="etag"{print $2}' | tr -d '\r')

# write only if nobody changed it since
curl -X PATCH "$TASKSMATE_API_URL/v1/tasks/T123456" \
  -H "Authorization: Bearer $TASKSMATE_TOKEN" -H "If-Match: $etag" \
  -H "Content-Type: application/json" -d '{"status": "completed"}'

Python

task = tm.tasks.get("T123456")
tm.tasks.update("T123456", {"status": "completed"}, if_match=task.etag)   # 412 if it changed

tm

tm tasks update T123456 --status completed   # reads the ETag first, sends If-Match

Two identical requests, one Idempotency-Key, one task

Idempotent creates

Idempotency-Key: Replay the first response for 24 h when the same request is retried with this key. A replayed answer carries Idempotent-Replayed: true. Keys live 24 h; use a fresh UUID per logical create.

• Same key, different request — This Idempotency-Key was first used for a different request (method, path or body).
• Same key, first still running — The first request with this Idempotency-Key has not finished; retry shortly.

The operations that honour it:

• projects.create POST /v1/projects
• tasks.create POST /v1/tasks
• task-comments.create POST /v1/task-comments
• task-comments.reply POST /v1/task-comments/reply
• goals.create POST /v1/projects/{project_id}/goals

The SDK and tm send a key on every create and reuse it for their retries.

ETags

Single reads return an ETag.

• If-None-Match on a read: An ETag you hold; unchanged → 304 with no body.
• If-Match on a write: The ETag you read; a stale one is a 412 and nothing is written.

PATCH, not PUT

PATCH changes only the fields you send; null clears one. Each resource’s PUT twin is deprecated — prefer PATCH:

• projects.replace PUT /v1/projects/{project_id}
• tasks.replace PUT /v1/tasks/{task_id}
• organization-members.replace PUT /v1/organization-members/{user_id}/{org_id}
• designations.replace PUT /v1/designations/{designation_id}
• project-members.replace PUT /v1/project-members/{user_id}/{project_id}
• teams.replace PUT /v1/teams/{team_id}
• teams.replace_member PUT /v1/teams/{team_id}/members/{user_id}
• goals.replace PUT /v1/projects/{project_id}/goals/{goal_id}