webmanager-mvp/project_docs/API_GOLDEN.md

API_GOLDEN.md

Dit document definieert stabiele API responses. Velden mogen niet wijzigen zonder golden tests te updaten.

Browse

GET /api/browse

Response shape:

{
  "path": "storage1",
  "directories": [],
  "files": []
}

File Ops (direct)

POST /api/files/mkdir

Success:

{ "path": "storage1/parent/new_dir" }

Conflict (already_exists):

{
  "error": {
    "code": "already_exists",
    "message": "Target path already exists",
    "details": { "path": "storage1/parent/new_dir" }
  }
}

Invalid name (invalid_request):

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid name",
    "details": { "name": "bad/name" }
  }
}

POST /api/files/rename

Success:

{ "path": "storage1/parent/new_name.ext" }

Conflict (already_exists) + invalid name (invalid_request) gebruiken dezelfde error-shape als mkdir.

POST /api/files/delete

Success (202):

{
  "task_id": "<uuid>",
  "status": "queued"
}

Non-empty directory:

{
  "error": {
    "code": "directory_not_empty",
    "message": "Directory is not empty",
    "details": { "path": "storage1/parent/non_empty" }
  }
}

Task-based create endpoints

POST /api/files/copy

POST /api/files/move

POST /api/files/delete

Success (202):

{
  "task_id": "<uuid>",
  "status": "queued"
}

Tasks read endpoints

GET /api/tasks

Response shape:

{
  "items": [
    {
      "id": "<uuid>",
      "operation": "copy",
      "status": "running",
      "source": "storage1/a.txt",
      "destination": "storage2/a.txt",
      "created_at": "2026-03-10T10:00:00Z",
      "finished_at": null
    }
  ]
}

GET /api/tasks/{task_id}

Response shape:

{
  "id": "<uuid>",
  "operation": "move",
  "status": "running",
  "source": "storage1/a.txt",
  "destination": "storage2/a.txt",
  "done_bytes": 1024,
  "total_bytes": 4096,
  "done_items": null,
  "total_items": null,
  "current_item": "storage1/a.txt",
  "failed_item": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-03-10T10:00:00Z",
  "started_at": "2026-03-10T10:00:01Z",
  "finished_at": null
}

Task not found:

{
  "error": {
    "code": "task_not_found",
    "message": "Task was not found",
    "details": { "task_id": "task-missing" }
  }
}