Locks

A Lock can be used by your custom-developed applications to implement file locking and concurrency features. These locks are advisory, meaning that while a lock can be created, it does not prevent other API requests from being processed concurrently. You are responsible for checking locks prior to accessing a file.

The lock feature is designed to emulate the locking functionality provided by WebDAV. For a deeper understanding of how the lock mechanism works, refer to the WebDAV specification, which outlines how these endpoints function.

Files.com's WebDAV offering and desktop app leverage this locking API to manage concurrent file operations, ensuring consistency when multiple users or systems interact with the same files. It is not used within the Files.com web interface.

List Locks by Path

Endpoint

GET/locks/{path}

Return Object

Lock[]

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDescription
path
string
Required		Path to operate on.
include_children
boolean		Include locks from children objects?

Additional Arguments

Example Request

curl "https://app.files.com/api/rest/v1/locks/{path}" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "path": "locked_file",
    "timeout": 1,
    "depth": "infinity",
    "recursive": true,
    "owner": "user",
    "scope": "shared",
    "exclusive": false,
    "token": "17c54824e9931a4688ca032d03f6663c",
    "type": "write",
    "allow_access_by_any_user": false,
    "user_id": 1,
    "username": ""
  }
]

Create Lock

Endpoint

POST/locks/{path}

Return Object

Lock

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDescription
path
string
Required		Path
allow_access_by_any_user
boolean		Can lock be modified by users other than its creator?
exclusive
boolean		Is lock exclusive?
recursive
boolean		Does lock apply to subfolders?
timeout
int64		Lock timeout in seconds

Example Request

curl https://app.files.com/api/rest/v1/locks/{path} \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"allow_access_by_any_user":false,"exclusive":false,"recursive":true,"timeout":1}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "path": "locked_file",
  "timeout": 1,
  "depth": "infinity",
  "recursive": true,
  "owner": "user",
  "scope": "shared",
  "exclusive": false,
  "token": "17c54824e9931a4688ca032d03f6663c",
  "type": "write",
  "allow_access_by_any_user": false,
  "user_id": 1,
  "username": ""
}

Delete Lock

Endpoint

DELETE/locks/{path}

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Request Parameters

ParameterDescription
path
string
Required		Path
token
string
Required		Lock token

Example Request

curl "https://app.files.com/api/rest/v1/locks/{path}" \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

The Lock Object

Some of the endpoints above return a Lock object. The attributes of this object are listed below.

AttributeDescription
path
string		Path. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
timeout
int64		Lock timeout in seconds
depth
string
recursive
boolean		Does lock apply to subfolders?
owner
string		Owner of the lock. This can be any arbitrary string.
scope
string
exclusive
boolean		Is lock exclusive?
token
string		Lock token. Use to release lock.
type
string
allow_access_by_any_user
boolean		Can lock be modified by users other than its creator?
user_id
int64		Lock creator user ID
username
string		Lock creator username

Example Lock Object

{
  "path": "locked_file",
  "timeout": 1,
  "depth": "infinity",
  "recursive": true,
  "owner": "user",
  "scope": "shared",
  "exclusive": false,
  "token": "17c54824e9931a4688ca032d03f6663c",
  "type": "write",
  "allow_access_by_any_user": false,
  "user_id": 1,
  "username": ""
}