Locks HTTP API

The /var endpoint is used to hold, renew and release a lock over a variable.

Lock Variable

The endpoint to create a variable can also be used to hold a lock and interact with it through the use of a parameter defining the operation to be performed.

Parameters

The lock operation parameter can be:

• lock-acquire: When used, the call will introduce a lock over the variable if it exists, or create a new one if it doesn't. The lock ID will be returned in the response and it must be provided to perform any other operation over the lock. The variable items can be updated at any time using the lock ID, but the lock parameters are unmmutable, attempting to modify them while a lock is present will generate an error.

In the case of attempting to acquire a variable that is already locked, a conflict response will be returned.

The lock-acquire operation will override the variable items if new values are present.

Sample Request

$ curl \
    -XPUT -d@spec.nsv.json \
    https://localhost:4646/v1/var/example/first?lock-acquire

Sample Payload

{
  "Namespace": "prod",
  "Path": "example/first",
  "Items": {
    "user": "me",
    "password": "passw0rd1"
  },
  "Lock": {
    "TTL": "15s",
    "LockDelay": "1m"
  }
}

Sample Response

The response body returns the created or updated variable including the lock parameters and ID, along with metadata created by the server:

{
  "CreateIndex": 15,
  "CreateTime": 1694552155379696000,
  "Items": {
    "user": "me",
    "password": "passw0rd1"
  },
  "Lock": {
    "TTL": "15s",
    "LockDelay": "15s",
    "ID": "670c7248-e2ef-f982-e4c5-f4437f75f1e4"
  },
  "ModifyIndex": 16,
  "ModifyTime": 1694552206138804000,
  "Namespace": "prod",
  "Path": "example/first"
}

• lock-renew: A valid call to lock renew needs to be placed before the lock's TTL is up in order to mantain the variable locked. A valid call must include the lock ID as part of the request body. If the lock TTL is up without a renewal or release calls, the variable will remain unlockable for at least the lock delay.

Sample Request

$ curl \
    -XPUT -d@spec.nsv.json \
    https://localhost:4646/v1/var/example/first?lock-renew

Sample Payload

{
  "Path": "example/first",
  "Namespace": "prod",
  "Lock": {
    "ID": "670c7248-e2ef-f982-e4c5-f4437f75f1e4"
  }
}

Sample Response

The response body only returns metadata created by the server and the lock parameters:

{
  "CreateIndex": 11,
  "CreateTime": 1694555280887153000,
  "Lock": {
    "TTL": "15s",
    "LockDelay": "15s",
    "ID": "670c7248-e2ef-f982-e4c5-f4437f75f1e4"
  },
  "ModifyIndex": 43,
  "ModifyTime": 1694556175092779000,
  "Namespace": "prod",
  "Path": "example/first"
}

• lock-release: A call to the endpoint with the lock-release operation will immediately remove the lock over the variable, making it modifiable without restrictions again.

The lock-release operation will not override the variable items, if the request body contains any item, it will generate a bad request response.

Sample Request

$ curl \
    -XPUT -d@spec.nsv.json \
    https://localhost:4646/v1/var/example/first?lock-release

Sample Payload

{
  "Path": "example/first",
  "Namespace": "prod",
  "Lock": {
    "ID": "670c7248-e2ef-f982-e4c5-f4437f75f1e4"
  }
}

Sample Response

The response body returns the released variable along with metadata created by the server:

{
  "CreateIndex": 11,
  "CreateTime": 1694555280887153000,
  "ModifyIndex": 66,
  "ModifyTime": 1694556922600469000,
  "Namespace": "prod",
  "Path": "example/first"
}

Sample Response for Conflict

In the case of an attempt to lock, renew or modify a locked variable without the correct ID, the API will return HTTP error code 409 and a response body showing the conflicting variable. If the provided ACL token does not also have read permissions to the variable path, the response will include only metadata and not the Items field:

{
  "CreateIndex": 0,
  "CreateTime": 0,
  "Items": null,
  "Lock": null,
  "ModifyIndex": 0,
  "ModifyTime": 0,
  "Namespace": "default",
  "Path": "example/first"
}

Restrictions

When creating a new variable using the lock-acquire operation, all the known restrictions regarding the path and size of the content apply, but unlike regular variables, locked variables can be created with or without any items.

The lock TTL and Delay must be values between 10 seconds and 24 hours.