kodi
189 lines
3.8 KiB
Markdown
189 lines
3.8 KiB
Markdown
# API_GOLDEN.md
|
|
|
|
Dit document definieert stabiele API responses.
|
|
Velden mogen niet wijzigen zonder golden tests te updaten.
|
|
|
|
## Browse
|
|
|
|
### `GET /api/browse`
|
|
Response shape:
|
|
```json
|
|
{
|
|
"path": "storage1",
|
|
"directories": [],
|
|
"files": []
|
|
}
|
|
```
|
|
|
|
## File Ops (direct)
|
|
|
|
### `POST /api/files/mkdir`
|
|
Success:
|
|
```json
|
|
{ "path": "storage1/parent/new_dir" }
|
|
```
|
|
|
|
Conflict (`already_exists`):
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "already_exists",
|
|
"message": "Target path already exists",
|
|
"details": { "path": "storage1/parent/new_dir" }
|
|
}
|
|
}
|
|
```
|
|
|
|
Invalid name (`invalid_request`):
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "invalid_request",
|
|
"message": "Invalid name",
|
|
"details": { "name": "bad/name" }
|
|
}
|
|
}
|
|
```
|
|
|
|
### `POST /api/files/rename`
|
|
Success:
|
|
```json
|
|
{ "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):
|
|
```json
|
|
{
|
|
"task_id": "<uuid>",
|
|
"status": "queued"
|
|
}
|
|
```
|
|
|
|
Non-empty directory:
|
|
```json
|
|
{
|
|
"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):
|
|
```json
|
|
{
|
|
"task_id": "<uuid>",
|
|
"status": "queued"
|
|
}
|
|
```
|
|
|
|
## Tasks read endpoints
|
|
|
|
### `GET /api/tasks`
|
|
Response shape:
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
```
|
|
|
|
Voor task-based file-actions `copy`, `move`, `duplicate` en `delete` betekenen progressvelden:
|
|
- `done_items`: aantal volledig verwerkte bestanden
|
|
- `total_items`: exact aantal te verwerken bestanden in de hele task
|
|
- `current_item`: taakrelatief bestandspad als beschikbaar, anders bestandsnaam
|
|
|
|
Voor `move` geldt een expliciete uitzondering:
|
|
- file-gebaseerde move-paden rapporteren file-progress
|
|
- same-root directory moves behouden directe rename-semantiek en rapporteren daarom grovere item-progress per directory-operatie
|
|
|
|
Voor `delete` geldt:
|
|
- recursive delete van directorytrees rapporteert file-progress per verwijderd bestand
|
|
- lege mappen of directory-only deletes houden `done_items = 0`, `total_items = 0` en gebruiken geen kunstmatige file-teller
|
|
|
|
### `POST /api/tasks/{task_id}/cancel`
|
|
Success for cancellable file-action task:
|
|
```json
|
|
{
|
|
"id": "<uuid>",
|
|
"operation": "copy",
|
|
"status": "cancelling",
|
|
"source": "2 items",
|
|
"destination": "storage1/dest",
|
|
"done_bytes": null,
|
|
"total_bytes": null,
|
|
"done_items": 0,
|
|
"total_items": 2,
|
|
"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
|
|
}
|
|
```
|
|
|
|
Not cancellable:
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "task_not_cancellable",
|
|
"message": "Task cannot be cancelled",
|
|
"details": { "task_id": "<uuid>", "status": "completed" }
|
|
}
|
|
}
|
|
```
|
|
|
|
Task not found:
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "task_not_found",
|
|
"message": "Task was not found",
|
|
"details": { "task_id": "task-missing" }
|
|
}
|
|
}
|
|
```
|