backend/docs/API.md

159 lines
6.9 KiB
Markdown

# danable API reference
Base URL: `http://localhost:8000/api/v1` (prefix from `config.yaml` `app.api_prefix`).
Interactive docs: `http://localhost:8000/docs`.
## Conventions
- Auth: `Authorization: Bearer <accessToken>` on every endpoint except those
marked Public. `GET /auth/login` with wrong credentials returns 401 and the
frontend redirects to `/login`.
- Tracing headers (optional in, always out): send `X-Session-ID` (one ID per
browser visit; server mints one if absent) and optionally `X-User-Id`.
Responses echo `X-Session-ID` and a per-request `X-Trace-ID`.
- Errors are JSON `{ detail: string }`. Common codes: `400` bad input,
`401` missing/invalid token, `404` unknown id, `409` slug/email conflict,
`422` validation, `503` R2 not configured (`.env` keys missing).
- Enums: `taskType`: `classification | object_detection | segmentation`;
image `status`: `unassigned | in_progress | pending_review | completed`;
shape `type`: `bbox | polygon | point`.
## System (Public)
| Method | Path | Description |
|---|---|---|
| GET | `/health` | Liveness incl. DB check, `{ ok: true }` |
| GET | `/metrics` | Phase-1 traffic counters per route |
| GET | `/` (root, no prefix) | Name, docs and health links |
| POST | `/admin/init-db` | Create tables, seed dev admin. Dev-only |
| POST | `/admin/backfill-thumbnails?limit=100` | Mint missing thumbs. Dev-only |
## Auth (Public)
`POST /auth/login` — body `{ email, password }` — returns:
```json
{
"user": { "id": "...", "name": "Admin", "email": "admin@danable.local",
"avatarInitials": "A", "avatarColor": "#3B82F6",
"role": "admin", "status": "active",
"isOnline": true, "lastActive": "..." },
"accessToken": "<jwt ~12h>",
"refreshToken": "<jwt 7d>"
}
```
`GET /auth/me` (auth) — current user in the same shape.
## Users (auth)
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/users` | — | All users `{ id, email, name, role, status, assignedProjectIds }` |
| POST | `/users` | `{ email, role, projectIds? }` | Invite (unusable password until set), `201` |
| PATCH | `/users/{id}` | `{ role?, status?, projectIds? }` | Role / suspend / project assignment |
Roles: `admin | manager | annotator | reviewer`. Status:
`active | invited | suspended` (suspended tokens are rejected).
## Projects (auth)
| Method | Path | Description |
|---|---|---|
| GET | `/projects` | Full project cards: `stats`, `classes`, `members`, `thumbnailUrl` |
| POST | `/projects` | `{ name, slug, description?, taskType }`, `201` |
| GET | `/projects/{id}` | Detail (same card shape) |
| PATCH | `/projects/{id}` | `{ name?, slug?, description?, task_type?, status? }` |
| DELETE | `/projects/{id}` | Cascades images, annotations, classes, exports, AI and action rows |
| POST | `/projects/{id}/classes` | `{ name, color?, shortcutKey? }`, `201` |
| PUT | `/projects/{id}/classes` | Bulk replace `[{ id?, name, color }]` (matches LabelsTab semantics) |
`stats` example: `{ totalImages, unassigned, inProgress, pendingReview,
completed, totalObjects }`. `members` are users assigned to the project with
per-member `assignedCount`.
## Images (auth)
Direct-to-R2 upload keeps bytes and bandwidth off the API:
1. `POST /projects/{id}/images/presign` `{ fileName, contentType }` →
`{ putUrl, r2Key }` (900s TTL).
2. `PUT <putUrl>` with the file bytes (`Content-Type` must match).
3. `POST /projects/{id}/images` `{ fileName, r2Key, width?, height? }` →
`201 { id, r2Key, url }`. Confirm verifies the object exists, writes the
metadata row and mints 512px + 128px thumbnails (fail-open).
`GET /projects/{id}/images` is paginated — never the whole dataset:
```text
GET /projects/{id}/images?status=all&search=img_&assignee=all&limit=50&offset=0
→ { "items": [ ... ], "total": 1000 }
```
`limit` clamps to 1..200 (config `max_page_size`). Item fields: `id`,
`projectId`, `fileName`, `url`, `thumbnailUrl` (512px), `thumbnailSmallUrl`
(128px, falls back up the chain), `width/height`, `status`, `objectCount`,
`assignedTo/assignedToName`, `reviewerName`, `classificationLabelId`, `flags`.
`PATCH /projects/{id}/images/{imageId}?status=completed` — status transition.
## Annotations (auth)
`GET /projects/{pid}/images/{iid}/annotation` — one row per image:
```json
{ "imageId": "...", "projectId": "...", "classificationLabelId": "cls-1",
"flags": { "blurryOrUncertain": false, "needsRecheck": false },
"shapes": [{ "id": "s1", "index": 1, "type": "bbox",
"labelId": "cls-1", "labelName": "car", "color": "#ff0000",
"visible": true, "bbox": { "x": 10, "y": 20, "width": 100, "height": 80 } }] }
```
`PUT` same path with `{ classificationLabelId?, flags?, shapes[] }` upserts
(one row per image, 404 when the image does not exist) and syncs
`object_count` / flags onto the image row. Also emits an `annotation.save`
action event. Polygon shapes use `points: [{x, y}]`, points use `point`.
## Events and activities
`POST /events` (Public, `202`) — client-side actions the backend never sees:
```json
{ "session_id": "…", "events": [
{ "action": "image.status", "project_id": "…", "image_id": "…",
"payload": { "from": "a", "to": "b" } } ] }
```
`session_id` is required; max 200 events/call. Enqueued to Redis and drained
into `action_events` (requeued on DB failure, never lost, never blocks).
`GET /activities?limit=30` (auth) — human feed derived from that table:
`[{ id, timestamp, userName, actionText, projectId }]`.
## Worked example (curl)
```bash
B=http://localhost:8000/api/v1
curl -s -X POST $B/admin/init-db
TOK=$(curl -s -X POST $B/auth/login -H 'Content-Type: application/json' \
-d '{"email":"admin@danable.local","password":"Admin123!"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])")
H="Authorization: Bearer $TOK"
PID=$(curl -s -X POST $B/projects -H "$H" -H 'Content-Type: application/json' \
-d '{"name":"Pho Co","slug":"pho-co","description":"e2e","taskType":"classification"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# upload one image
PRE=$(curl -s -X POST $B/projects/$PID/images/presign -H "$H" \
-H 'Content-Type: application/json' -d '{"fileName":"s.jpg","contentType":"image/jpeg"}')
PUTURL=$(echo "$PRE" | python3 -c "import sys,json; print(json.load(sys.stdin)['putUrl'])")
R2KEY=$(echo "$PRE" | python3 -c "import sys,json; print(json.load(sys.stdin)['r2Key'])")
curl -s -o /dev/null -w "%{http_code}\n" -X PUT -H 'Content-Type: image/jpeg' \
--data-binary @photo.jpg "$PUTURL"
IID=$(curl -s -X POST $B/projects/$PID/images -H "$H" -H 'Content-Type: application/json' \
-d "{\"fileName\":\"s.jpg\",\"r2Key\":\"$R2KEY\",\"width\":1280,\"height\":720}" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# classify + complete
curl -s -X PUT $B/projects/$PID/images/$IID/annotation -H "$H" \
-H 'Content-Type: application/json' -d '{"shapes":[],"flags":{}}'
curl -s -X PATCH "$B/projects/$PID/images/$IID?status=completed" -H "$H"
```