Directory operations

Overview

Sections with tree structure support nested directories of arbitrary depth. Directory creation, deletion, and clearing are available for them.

The section structure is stated in its article and comes in the structure field of the section description. In sections with flat structure, directory operations are not supported.

Deleting and clearing a non-empty directory are performed with two requests. The first request deletes nothing: it returns a confirmation key and the scope of the upcoming operation. The second performs the operation with this key. The rationale for this order is described in section Confirming an operation with a key.

Requests

HTTP verb Endpoint Description

PUT

/rest/v1/fs/targets/<target>/<path>/

Creating a directory

DELETE

/rest/v1/fs/targets/<target>/<path>

Deleting a directory

CLEAR

/rest/v1/fs/targets/<target>/<path>

Clearing a directory


Creating a directory

Creates a directory at the specified path along with missing intermediate directories.

Specifics

  • The path is specified with a trailing slash: this is what distinguishes directory creation from file upload.

  • The request body is absent and ignored.

  • Creating directories separately for file uploads is not required: the PUT method on a file path creates the entire path itself. The operation is needed where the directory must exist on its own — for example, to prepare the structure in advance.

Request

Example request
PUT /rest/v1/fs/targets/files/certificates/2026/ HTTP/1.1
Content-Length: 0

Response

Code Condition

201

Directory created.

204

Directory already existed.

409

A file is located at the specified path.

405

The section does not support nested directories.


Deleting a directory

Specifics

  • Without the recursive parameter only an empty directory is deleted; a non-empty one returns 409.

  • The section root cannot be deleted: DELETE on the collection path always returns 405. To delete the contents of a section, use Clearing a directory.

  • A trailing slash in the path is allowed and means the assertion "the target must be a directory": if a file is at the path, 409 is returned rather than deletion. Without the slash, the target type is determined by the file system.

  • Emptied parent directories are deleted automatically, as when deleting a file.

Request

Deleting an empty directory
DELETE /rest/v1/fs/targets/files/certificates/2026 HTTP/1.1
Deleting a directory with contents, first request
DELETE /rest/v1/fs/targets/files/certificates?recursive=true HTTP/1.1
Deleting a directory with contents, second request
DELETE /rest/v1/fs/targets/files/certificates?recursive=true&key=493769f214f028c0a415888026352bbf HTTP/1.1

Response

Code Condition

204

Directory deleted.

409

The directory is not empty and the recursive parameter is not specified; or the key did not match; or the scope exceeds the boundaries.

428

Confirmation required: the key and operation scope are in the body.

404

The directory does not exist.

405

The section root is specified.


Clearing a directory

Deletes all directory contents, leaving the directory itself existing.

Specifics

  • The operation is always recursive and does not accept the recursive parameter: nested directories are deleted along with files.

  • It also applies to the section root: the section contents are cleared, the section itself remains.

  • It requires key confirmation on par with recursive deletion.

Request

First request
CLEAR /rest/v1/fs/targets/files/certificates HTTP/1.1
Second request
CLEAR /rest/v1/fs/targets/files/certificates?key=493769f214f028c0a415888026352bbf HTTP/1.1

Confirming an operation with a key

Recursive deletion and clearing are irreversible and can destroy the contents of an entire section in one request. Therefore they are split into two dependent steps.

First request

Returns 428 Precondition Required and deletes nothing:

HTTP/1.1 428 Precondition Required
Content-Type: application/json; charset=utf-8

{
  "error_code" : 1428,
  "error_message" : "Confirmation required",
  "confirmation_key" : "493769f214f028c0a415888026352bbf",
  "expires_in" : 97,
  "entries" : {
    "files" : 128,
    "directories" : 3,
    "bytes" : 41207332,
    "truncated" : false
  }
}

The entries field describes the scope of the upcoming operation — it should be shown to the user before confirmation. The expires_in field contains the exact number of seconds remaining until the key expires and is suitable for displaying a timer.

Second request

The same request with the key parameter. If the key matches, the operation is performed and 204 No Content is returned.

Key properties

  • The key is computed, not stored: the server does not keep issued keys in memory or accumulate them.

  • The key is bound to the session, section, path, method, and directory contents. A key issued for deletion will not work for clearing, and a key from one directory will not work for another.

  • The validity period is 60 to 120 seconds; the exact remaining time comes in expires_in.

  • If the directory contents change between requests, the key stops matching. This is intentional: confirmation received for 128 files should not delete a thousand that grew in the meantime.

Handling failure on the second request

The second request may return 409 or 428 again. Both cases are handled identically: repeat the first request, show the user the updated scope, and request confirmation again.

A repeated 428 is not an error: it comes, in particular, after activation of a new platform configuration that changes the key computation basis.

Scope limits

Recursive operations are limited by the values coming in limits.recursive_delete of the section description: by default 10,000 files and 10 GB.

Archive packing and unpacking limits are set separately and lower — see Download and upload a directory as an archive. A directory that cannot be downloaded as an archive can still be deleted or cleared: deletion does not read the contents.

If exceeded, 409 is returned and deletion is not performed at all — no partial deletion occurs. The "truncated": true flag in the first request response means the directory definitely exceeds the boundary: such a directory will have to be deleted in parts.

The limit also protects against prolonged connection blocking: the operation is performed synchronously.

See also