PdfEditor/docs/API.md

Contrat d'API — PdfEditor

Document de référence partagé entre l'agent backend (Go) et l'agent frontend (Angular). Toute évolution doit être répercutée des deux côtés.

Base URL : /api Auth : JWT Bearer dans l'en-tête Authorization: Bearer <access_token>. Format : JSON (sauf upload/download de fichier).

Conventions

• Codes d'erreur : 400 (validation), 401 (non authentifié), 403 (interdit), 404 (introuvable), 409 (conflit, ex. email déjà pris), 500.
• Corps d'erreur : { "error": "message lisible" }.
• Dates : ISO 8601 (RFC 3339).
• Les access_token sont de courte durée (15 min). Les refresh_token permettent d'obtenir un nouveau couple de tokens.

Authentification

POST /api/auth/register

Req: { "email": "a@b.c", "password": "..." } Res 201: { "user": { "id", "email", "created_at" }, "access_token", "refresh_token" }

POST /api/auth/login

Req: { "email", "password" } Res 200: { "user": {...}, "access_token", "refresh_token" }

POST /api/auth/refresh

Req: { "refresh_token": "..." } Res 200: { "access_token", "refresh_token" }

POST /api/auth/logout

Auth requise. Invalide le refresh token courant. Res 204.

GET /api/me

Auth requise. Res 200: { "id", "email", "created_at" }

Documents

Toutes ces routes nécessitent l'authentification. Un utilisateur ne voit que ses propres documents.

GET /api/documents

Res 200: { "documents": [ { "id", "name", "size", "created_at", "updated_at" } ] }

POST /api/documents

Upload d'un nouveau PDF. multipart/form-data :

• file : le binaire PDF (obligatoire)
• name : nom affiché (optionnel, défaut = nom du fichier) Res 201: { "id", "name", "size", "created_at", "updated_at" }

GET /api/documents/:id

Métadonnées. Res 200: { "id", "name", "size", "created_at", "updated_at" }

GET /api/documents/:id/file

Renvoie le binaire PDF. Content-Type: application/pdf.

PUT /api/documents/:id

Met à jour le PDF (après édition) et/ou le nom. multipart/form-data :

• file : nouveau binaire PDF (optionnel)
• name : nouveau nom (optionnel) Res 200: métadonnées à jour.

DELETE /api/documents/:id

Res 204.

Santé

GET /api/health

Res 200: { "status": "ok" } — utilisé par les healthchecks/monitoring.

Modèle de données (backend)

• users : id (uuid), email (unique), password_hash, created_at
• refresh_tokens : id, user_id, token_hash, expires_at, revoked
• documents : id (uuid), user_id (fk), name, file_path, size, created_at, updated_at

Notes d'intégration frontend

• Le frontend stocke access_token en mémoire et refresh_token de façon persistante ; un intercepteur HTTP ajoute le Bearer et tente un /auth/refresh sur 401.
• En prod, nginx (image frontend) proxifie /api/* vers le service backend:8080. En dev (docker-compose.local.yml), même comportement via nginx, ou proxy Angular vers http://localhost:8081.