Skip to content

batch-operations.md

Latest commit

 

History

History
120 lines (92 loc) · 3.11 KB

batch-operations.md

File metadata and controls

120 lines (92 loc) · 3.11 KB

Batch Operations

OxiCloud exposes batch endpoints for bulk file and folder operations under /api/batch. Batch requests reduce round-trips, run concurrently behind a semaphore, and return per-item success and failure details instead of aborting on the first error.

What You Can Do

File operations

Method Path Description
POST /api/batch/files/move Move multiple files into a target folder
POST /api/batch/files/copy Copy multiple files into a target folder
POST /api/batch/files/delete Delete multiple files
POST /api/batch/files/get Fetch metadata for multiple files

Folder operations

Method Path Description
POST /api/batch/folders/delete Delete multiple folders
POST /api/batch/folders/create Create multiple folders
POST /api/batch/folders/get Fetch metadata for multiple folders
POST /api/batch/folders/move Move multiple folders

Additional batch endpoints

Method Path Description
POST /api/batch/trash Trash multiple items in one request
POST /api/batch/download Build a batch download

Request Shapes

File move or copy

{
  "file_ids": ["id-1", "id-2", "id-3"],
  "target_folder_id": "folder-abc"
}

Folder delete

{
  "folder_ids": ["folder-1", "folder-2"],
  "recursive": true
}

Folder create

{
  "folders": [
    { "name": "Documents", "parent_id": null },
    { "name": "Photos", "parent_id": "folder-abc" }
  ]
}

Response Format

All batch endpoints return the same envelope:

{
  "successful": [
    { "id": "id-1" }
  ],
  "failed": [
    { "id": "bad-id", "error": "File not found" }
  ],
  "stats": {
    "total": 5,
    "successful": 4,
    "failed": 1,
    "execution_time_ms": 245
  }
}

Status codes

Code Meaning
200 OK or 201 Created Every operation succeeded
206 Partial Content Some operations succeeded and some failed
400 Bad Request Every operation failed

Concurrency Model

Batch work is coordinated by BatchOperationService and a tokio::sync::Semaphore. By default, OxiCloud caps concurrent work with max_concurrent_files = 10 so large batches do not starve the rest of the application.

Individual failures are collected in the failed array. One bad item does not cancel the whole request unless the batch cannot start at all.

Example

# Move three files into a folder
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_ids":["id-1","id-2","id-3"],"target_folder_id":"folder-abc"}' \
  "https://oxicloud.example.com/api/batch/files/move"

# Delete multiple folders recursively
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_ids":["old-1","old-2"],"recursive":true}' \
  "https://oxicloud.example.com/api/batch/folders/delete"

Related Pages