Backend API: auth, projects/images/annotations, R2 presign, tracing, thumbnails, pagination, tests, docs
This commit is contained in:
parent
5c5deed2f5
commit
f8ed08b854
49 changed files with 2626 additions and 0 deletions
159
docs/API.md
Normal file
159
docs/API.md
Normal file
|
|
@ -0,0 +1,159 @@
|
|||
# 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"
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue