Lox API documentation

http://lox.yourdomain.com

Lox: A simple distributed lock manager

Lox exposes an HTTP API to help you manage distributed locks. That API is documented here.

You may also be interested in the product page or the GitHub repository

/health

Health check endpoint

get

Health check endpoint

get

Returns 200 if the service is available

Returns 200 if the service is available

HTTP status code 200

The Lox service is available and serving requests

/lock

Endpoints to acquire and release a single distributed lock

get post

Endpoints to acquire and release a single distributed lock

get

Retrieve current information on a shared lock.

 post

Attempt to acquire a shared lock.

Retrieve current information on a shared lock.

Query Parameters

  • key required (string)

    An identifier for the shared lock you want to acquire

    Example:

    lox.shared.lock.123

HTTP status code 200

Information on the shared lock

Body

Type: application/json

Example:

{"heldLocks": 5}

Attempt to acquire a shared lock.

Query Parameters

  • key required (string)

    An identifier for the shared lock you want to acquire

    Example:

    lox.shared.lock.123

  • maximumLocks required (integer)

    The maximum allowable number of held locks after a successful lock acquisition. If this many locks or more are already held, acquisition will fail.

    Example:

    5

  • ttlSeconds required (number)

    The number of seconds for which to hold the lock

    Example:

    60

HTTP status code 201

Successfully acquired a shared lock

Body

Type: application/json

Example:

{"lockId": "3885b1e0-022c-11e4-b7c7-6b932dd1bfa1"}

HTTP status code 204

Could not acquire a shared lock subject to maximumLocks

delete

delete

Release a held lock.

Release a held lock.

URI Parameters

  • lockId: required (string)

Query Parameters

  • lockId required (string)

    The lock ID provided by a previously successful lock acquisition

    Example:

    3885b1e0-022c-11e4-b7c7-6b932dd1bfa1

HTTP status code 204

If a lock was held, it has been released

/locks

Endpoints to acquire multiple distributed locks

post

Endpoints to acquire multiple distributed locks

post

Attempt to acquire multiple distributed locks subject to the same constraints on availability and TTL. Acquisition is all-or-nothing.

Attempt to acquire multiple distributed locks subject to the same constraints on availability and TTL. Acquisition is all-or-nothing.

Query Parameters

  • keys required (string)

    A list of string identifiers for the shared locks you want to acquire.

    Example:

    ["lox.shared.lock.123", "lox.shared.lock.456"]

  • maximumLocks required (integer)

    The maximum allowable number of held locks after a successful lock acquisition. If this many locks or more are already held by any of the keys, acquisition of all locks in the request will fail.

    Example:

    5

  • ttlSeconds required (number)

    The number of seconds for which to hold each lock.

    Example:

    60

HTTP status code 201

Successfully acquired a shared lock on every key in keys

Body

Type: application/json

Example:

{"lockIds":
  {"lox.shared.lock.123": "3885b1e0-022c-11e4-b7c7-6b932dd1bfa1",
   "lox.shared.lock.456": "3885b1e1-022c-11e4-b7c7-6b932dd1bfa1"}
}

HTTP status code 204

Could not acquire these shared locks subject to maximumLocks