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 |
|---|---|---|
|
|
|
|
|
|
|
|
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
PUTmethod 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.
Deleting a directory
Specifics
-
Without the
recursiveparameter only an empty directory is deleted; a non-empty one returns409. -
The section root cannot be deleted:
DELETEon the collection path always returns405. 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,
409is 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
DELETE /rest/v1/fs/targets/files/certificates/2026 HTTP/1.1
DELETE /rest/v1/fs/targets/files/certificates?recursive=true HTTP/1.1
DELETE /rest/v1/fs/targets/files/certificates?recursive=true&key=493769f214f028c0a415888026352bbf HTTP/1.1
Response
| Code | Condition |
|---|---|
|
Directory deleted. |
|
The directory is not empty and the |
|
Confirmation required: the key and operation scope are in the body. |
|
The directory does not exist. |
|
The section root is specified. |
Clearing a directory
Deletes all directory contents, leaving the directory itself existing.
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
-
Metadata (METADATA) — how to find out the directory scope without starting an operation.