83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
# 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`.
|