docs: migrate legacy docs to official site

2026-04-22 07:50:41 +02:00
parent e10a908f07
commit c0cb86c273
63 changed files with 1646 additions and 10136 deletions
@@ -0,0 +1,120 @@
+# 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
+
+```json
+{
+  "file_ids": ["id-1", "id-2", "id-3"],
+  "target_folder_id": "folder-abc"
+}
+```
+
+### Folder delete
+
+```json
+{
+  "folder_ids": ["folder-1", "folder-2"],
+  "recursive": true
+}
+```
+
+### Folder create
+
+```json
+{
+  "folders": [
+    { "name": "Documents", "parent_id": null },
+    { "name": "Photos", "parent_id": "folder-abc" }
+  ]
+}
+```
+
+## Response Format
+
+All batch endpoints return the same envelope:
+
+```json
+{
+  "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
+
+```bash
+# 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
+
+- [Search](/guide/search)
+- [Trash & Recycle Bin](/guide/trash)
+- [ZIP and Compression](/guide/zip-and-compression)