Skip to main content

Locking

An application can be worked by more than one person: an officer drafting, a clerk attaching a certificate, a supervisor correcting an address. The edit lock keeps them from silently overwriting each other.

The lock is advisory. It does not reject a write on its own; it tells you someone else is editing so your client can say so instead of racing them.

Check before you edit​

curl -s "$BASE/warrants/$WARRANT_ID/lock" -H "x-api-key: $API_KEY"
{
  "is_mine": false,
  "locked_by_user_id": "a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90",
  "locked_by_name": "Dr. Alex Chen",
  "locked_at": "2026-08-19T14:38:02Z",
  "expires_in_seconds": 240
}

An unlocked application returns is_mine: false with a null holder. Reading the state never claims it.

Claim​

curl -s -X POST "$BASE/warrants/$WARRANT_ID/lock" \
  -H "x-api-key: $API_KEY" \
  -H "X-On-Behalf-Of: dr.chen@example.gov"

Three outcomes:

  • Nobody holds it: you get it, and the response has is_mine: true.
  • You already hold it: the lock is refreshed. Claiming again is the heartbeat.
  • Somebody else holds a fresh lock: 409 lock_held, with their name in the body so you can show "Dr. Chen is editing".

A lock that has gone stale, meaning its holder stopped refreshing, is taken over by the next claimant. Nobody can strand an application by closing a laptop.

Refresh while editing​

Claim again every minute or so while a person has the application open. expires_in_seconds tells you how long the current claim has left; refresh well before it reaches zero.

Release​

curl -s -X DELETE "$BASE/warrants/$WARRANT_ID/lock" \
  -H "x-api-key: $API_KEY" \
  -H "X-On-Behalf-Of: dr.chen@example.gov"

Release when the person closes the editor, saves, or navigates away. Releasing a lock you do not hold does nothing and is not an error. Administrators can force-release anyone's lock, which is the escape hatch when a shift ends mid-edit.

A safe edit sequence​

POST   /v1/warrants/{id}/lock        claim, or show who has it
GET    /v1/warrants/{id}             read the current form_data
POST   /v1/warrants/{id}/lock        refresh while the person edits
PUT    /v1/warrants/{id}             write the whole form_data back
DELETE /v1/warrants/{id}/lock        release

Because updates replace form_data wholesale, the read has to be inside the lock. Reading before claiming, then writing afterwards, is exactly the race the lock exists to prevent.

For a single-writer integration that owns its applications end to end, locking is optional. For anything a person also touches through the eCourtDate application, take the lock.