# 🔌 Liste Exhaustive des Endpoints Backend API

> **Document de référence complet pour tous les endpoints de l'API Veza Backend**
> 
> Ce document liste TOUS les endpoints disponibles dans l'API backend, organisés par domaine fonctionnel.

---

## 📊 Statistiques

- **Total Endpoints**: 150+
- **Endpoints Publics**: 25
- **Endpoints Protégés**: 125+
- **Endpoints Admin**: 15
- **Méthodes HTTP**: GET, POST, PUT, DELETE, PATCH

---

## 🔐 1. AUTHENTICATION & AUTHORIZATION

### 1.1 Registration & Login

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/auth/register` | ❌ Public | Inscription d'un nouvel utilisateur |
| `POST` | `/api/v1/auth/login` | ❌ Public | Connexion utilisateur (email + password) |
| `POST` | `/api/v1/auth/refresh` | ❌ Public | Rafraîchir le token JWT |
| `POST` | `/api/v1/auth/logout` | ✅ Protected | Déconnexion utilisateur |
| `GET` | `/api/v1/auth/me` | ✅ Protected | Obtenir les infos de l'utilisateur connecté |

**Rate Limiting:**
- Register: Limité (désactivé en dev)
- Login: Limité (actif)

---

### 1.2 Email Verification

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/auth/verify-email` | ❌ Public | Vérifier l'email avec le token |
| `POST` | `/api/v1/auth/resend-verification` | ❌ Public | Renvoyer l'email de vérification |

**Rate Limiting:**
- Verify Email: Limité
- Resend Verification: Limité

---

### 1.3 Password Reset

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/auth/password/reset-request` | ❌ Public | Demander réinitialisation mot de passe |
| `POST` | `/api/v1/auth/password/reset` | ❌ Public | Réinitialiser le mot de passe avec token |

**Rate Limiting:**
- Password Reset: Limité

---

### 1.4 Two-Factor Authentication (2FA)

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/auth/2fa/setup` | ✅ Protected | Configurer 2FA (génère QR code) |
| `POST` | `/api/v1/auth/2fa/verify` | ✅ Protected | Vérifier code 2FA |
| `POST` | `/api/v1/auth/2fa/disable` | ✅ Protected | Désactiver 2FA |
| `GET` | `/api/v1/auth/2fa/status` | ✅ Protected | Obtenir statut 2FA |

---

### 1.5 OAuth

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/auth/oauth/providers` | ❌ Public | Liste des providers OAuth disponibles |
| `GET` | `/api/v1/auth/oauth/:provider` | ❌ Public | Initier flow OAuth (Google, GitHub, Discord) |
| `GET` | `/api/v1/auth/oauth/:provider/callback` | ❌ Public | Callback OAuth après authentification |

**Providers supportés:**
- Google
- GitHub
- Discord

---

### 1.6 Username Validation

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/auth/check-username` | ❌ Public | Vérifier disponibilité username |

---

## 👤 2. USERS & PROFILES

### 2.1 User Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/users` | ❌ Public | Liste des utilisateurs (paginée) |
| `GET` | `/api/v1/users/:id` | ❌ Public | Obtenir profil utilisateur par ID |
| `GET` | `/api/v1/users/by-username/:username` | ❌ Public | Obtenir profil par username |
| `GET` | `/api/v1/users/search` | ❌ Public | Rechercher des utilisateurs |
| `PUT` | `/api/v1/users/:id` | ✅ Owner/Admin | Mettre à jour profil utilisateur |
| `DELETE` | `/api/v1/users/:id` | ✅ Owner/Admin | Supprimer utilisateur (soft delete) |
| `GET` | `/api/v1/users/:id/completion` | ✅ Protected | Obtenir % complétion profil |

---

### 2.2 Avatar Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/users/:id/avatar` | ✅ Owner/Admin | Upload avatar utilisateur |
| `DELETE` | `/api/v1/users/:id/avatar` | ✅ Owner/Admin | Supprimer avatar utilisateur |

---

### 2.3 Social Features

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/users/:id/follow` | ✅ Protected | Suivre un utilisateur |
| `DELETE` | `/api/v1/users/:id/follow` | ✅ Protected | Ne plus suivre un utilisateur |
| `POST` | `/api/v1/users/:id/block` | ✅ Protected | Bloquer un utilisateur |
| `DELETE` | `/api/v1/users/:id/block` | ✅ Protected | Débloquer un utilisateur |

---

### 2.4 User Roles

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/users/:id/roles` | ✅ Admin | Assigner un rôle à un utilisateur |
| `DELETE` | `/api/v1/users/:id/roles/:roleId` | ✅ Admin | Révoquer un rôle d'un utilisateur |

---

### 2.5 User Liked Tracks

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/users/:id/likes` | ✅ Protected | Obtenir les tracks likés par l'utilisateur |

---

### 2.6 Data Export (GDPR)

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/users/me/export` | ✅ Protected | Exporter toutes les données utilisateur (JSON) |

---

## 🎵 3. TRACKS & AUDIO

### 3.1 Track Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks` | ❌ Public | Liste des tracks (paginée, filtrée) |
| `GET` | `/api/v1/tracks/:id` | ❌ Public | Obtenir détails d'une track |
| `POST` | `/api/v1/tracks` | ✅ Creator/Premium/Admin | Upload une nouvelle track |
| `PUT` | `/api/v1/tracks/:id` | ✅ Owner/Admin | Mettre à jour une track |
| `DELETE` | `/api/v1/tracks/:id` | ✅ Owner/Admin | Supprimer une track |

---

### 3.2 Track Search

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks/search` | ❌ Public | Rechercher des tracks |

**Filtres supportés:**
- Query (titre, artiste, album)
- Genre
- Tags
- Date range
- Duration range

---

### 3.3 Track Stats & History

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks/:id/stats` | ❌ Public | Statistiques d'une track |
| `GET` | `/api/v1/tracks/:id/history` | ❌ Public | Historique des versions |

---

### 3.4 Track Download

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks/:id/download` | ❌ Public | Télécharger une track |

---

### 3.5 Track Sharing

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks/shared/:token` | ❌ Public | Accéder à une track via lien de partage |
| `POST` | `/api/v1/tracks/:id/share` | ✅ Protected | Créer un lien de partage |
| `DELETE` | `/api/v1/tracks/share/:id` | ✅ Protected | Révoquer un lien de partage |

---

### 3.6 Chunked Upload

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks/:id/status` | ✅ Protected | Statut d'upload d'une track |
| `POST` | `/api/v1/tracks/initiate` | ✅ Protected | Initier upload chunked |
| `POST` | `/api/v1/tracks/chunk` | ✅ Protected | Upload un chunk |
| `POST` | `/api/v1/tracks/complete` | ✅ Protected | Compléter upload chunked |
| `GET` | `/api/v1/tracks/quota/:id` | ✅ Protected | Obtenir quota d'upload |
| `GET` | `/api/v1/tracks/resume/:uploadId` | ✅ Protected | Reprendre un upload |

---

### 3.7 Batch Operations

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/tracks/batch/delete` | ✅ Protected | Supprimer plusieurs tracks |
| `POST` | `/api/v1/tracks/batch/update` | ✅ Protected | Mettre à jour plusieurs tracks |

---

### 3.8 Track Social

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/tracks/:id/like` | ✅ Protected | Liker une track |
| `DELETE` | `/api/v1/tracks/:id/like` | ✅ Protected | Unliker une track |
| `GET` | `/api/v1/tracks/:id/likes` | ✅ Protected | Obtenir les likes d'une track |

---

### 3.9 Track Versions

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/tracks/:id/versions/:versionId/restore` | ✅ Protected | Restaurer une version de track |

---

### 3.10 Track Analytics

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/tracks/:id/play` | ✅ Protected | Enregistrer une lecture de track |

---

### 3.11 HLS Streaming

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks/:id/hls/info` | ❌ Public | Obtenir infos stream HLS |
| `GET` | `/api/v1/tracks/:id/hls/status` | ❌ Public | Obtenir statut stream HLS |

---

### 3.12 Track Comments

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/tracks/:id/comments` | ❌ Public | Obtenir commentaires d'une track |
| `POST` | `/api/v1/tracks/:id/comments` | ✅ Protected | Ajouter un commentaire |
| `DELETE` | `/api/v1/comments/:id` | ✅ Protected | Supprimer un commentaire |

---

## 📝 4. PLAYLISTS

### 4.1 Playlist Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/playlists` | ✅ Protected | Liste des playlists de l'utilisateur |
| `POST` | `/api/v1/playlists` | ✅ Protected | Créer une playlist |
| `GET` | `/api/v1/playlists/:id` | ✅ Protected | Obtenir détails d'une playlist |
| `PUT` | `/api/v1/playlists/:id` | ✅ Owner/Admin | Mettre à jour une playlist |
| `DELETE` | `/api/v1/playlists/:id` | ✅ Owner/Admin | Supprimer une playlist |

---

### 4.2 Playlist Search & Discovery

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/playlists/search` | ✅ Protected | Rechercher des playlists |
| `GET` | `/api/v1/playlists/recommendations` | ✅ Protected | Obtenir recommandations de playlists |

---

### 4.3 Playlist Tracks

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/playlists/:id/tracks` | ✅ Protected | Ajouter une track à la playlist |
| `DELETE` | `/api/v1/playlists/:id/tracks/:track_id` | ✅ Protected | Retirer une track de la playlist |
| `PUT` | `/api/v1/playlists/:id/tracks/reorder` | ✅ Protected | Réorganiser les tracks |

---

### 4.4 Playlist Collaborators

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/playlists/:id/collaborators` | ✅ Protected | Obtenir collaborateurs |
| `POST` | `/api/v1/playlists/:id/collaborators` | ✅ Owner/Admin | Ajouter un collaborateur |
| `PUT` | `/api/v1/playlists/:id/collaborators/:userId` | ✅ Owner/Admin | Modifier permissions collaborateur |
| `DELETE` | `/api/v1/playlists/:id/collaborators/:userId` | ✅ Owner/Admin | Retirer un collaborateur |

---

### 4.5 Playlist Sharing

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/playlists/:id/share` | ✅ Owner/Admin | Créer lien de partage |

---

## 🛒 5. MARKETPLACE

### 5.1 Products

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/marketplace/products` | ❌ Public | Liste des produits |
| `POST` | `/api/v1/marketplace/products` | ✅ Creator/Premium/Admin | Créer un produit |
| `PUT` | `/api/v1/marketplace/products/:id` | ✅ Owner/Admin | Mettre à jour un produit |

---

### 5.2 Orders

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/marketplace/orders` | ✅ Protected | Liste des commandes |
| `GET` | `/api/v1/marketplace/orders/:id` | ✅ Protected | Détails d'une commande |
| `POST` | `/api/v1/marketplace/orders` | ✅ Protected | Créer une commande |

---

### 5.3 Downloads

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/marketplace/download/:product_id` | ✅ Protected | Obtenir URL de téléchargement |

---

## 💬 6. CHAT & MESSAGING

### 6.1 Chat Token

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/chat/token` | ✅ Protected | Obtenir token pour chat en temps réel |
| `GET` | `/api/v1/chat/stats` | ✅ Protected | Statistiques du chat |

---

### 6.2 Conversations (Rooms)

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/conversations` | ✅ Protected | Liste des conversations |
| `POST` | `/api/v1/conversations` | ✅ Protected | Créer une conversation |
| `GET` | `/api/v1/conversations/:id` | ✅ Protected | Détails d'une conversation |
| `PUT` | `/api/v1/conversations/:id` | ✅ Protected | Mettre à jour une conversation |
| `DELETE` | `/api/v1/conversations/:id` | ✅ Protected | Supprimer une conversation |
| `GET` | `/api/v1/conversations/:id/history` | ✅ Protected | Historique des messages |

---

### 6.3 Participants

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/conversations/:id/members` | ✅ Protected | Ajouter un membre (legacy) |
| `POST` | `/api/v1/conversations/:id/participants` | ✅ Protected | Ajouter un participant |
| `DELETE` | `/api/v1/conversations/:id/participants/:userId` | ✅ Protected | Retirer un participant |

---

## 🔔 7. NOTIFICATIONS

### 7.1 Notification Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/notifications` | ✅ Protected | Liste des notifications |
| `POST` | `/api/v1/notifications/:id/read` | ✅ Protected | Marquer comme lu |
| `POST` | `/api/v1/notifications/read-all` | ✅ Protected | Tout marquer comme lu |

---

## 🎭 8. ROLES & PERMISSIONS

### 8.1 Roles

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/roles` | ✅ Protected | Liste des rôles |
| `GET` | `/api/v1/roles/:id` | ✅ Protected | Détails d'un rôle |

---

## 🔗 9. WEBHOOKS

### 9.1 Webhook Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/webhooks` | ✅ Protected | Liste des webhooks |
| `POST` | `/api/v1/webhooks` | ✅ Protected | Créer un webhook |
| `DELETE` | `/api/v1/webhooks/:id` | ✅ Protected | Supprimer un webhook |
| `GET` | `/api/v1/webhooks/stats` | ✅ Protected | Statistiques des webhooks |
| `POST` | `/api/v1/webhooks/:id/test` | ✅ Protected | Tester un webhook |
| `POST` | `/api/v1/webhooks/:id/regenerate-key` | ✅ Protected | Régénérer clé API webhook |

---

## 📊 10. ANALYTICS

### 10.1 Analytics Events

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/analytics/events` | ✅ Protected | Enregistrer un événement analytics |
| `GET` | `/api/v1/analytics/tracks/:id` | ✅ Protected | Dashboard analytics d'une track |

---

## 🔐 11. SESSIONS

### 11.1 Session Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/sessions` | ✅ Protected | Liste des sessions actives |
| `POST` | `/api/v1/sessions/logout` | ✅ Protected | Déconnexion session courante |
| `POST` | `/api/v1/sessions/logout-all` | ✅ Protected | Déconnexion toutes sessions |
| `DELETE` | `/api/v1/sessions/:session_id` | ✅ Protected | Révoquer une session |
| `GET` | `/api/v1/sessions/stats` | ✅ Protected | Statistiques des sessions |
| `POST` | `/api/v1/sessions/refresh` | ✅ Protected | Rafraîchir une session |

---

## 📤 12. UPLOADS

### 12.1 Upload Management

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/uploads` | ✅ Protected | Upload un fichier |
| `POST` | `/api/v1/uploads/batch` | ✅ Protected | Upload multiple fichiers |
| `GET` | `/api/v1/uploads/:id/status` | ✅ Protected | Statut d'un upload |
| `GET` | `/api/v1/uploads/:id/progress` | ✅ Protected | Progression d'un upload |
| `DELETE` | `/api/v1/uploads/:id` | ✅ Protected | Annuler/supprimer un upload |
| `GET` | `/api/v1/uploads/stats` | ✅ Protected | Statistiques des uploads |

---

### 12.2 Upload Info (Public)

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/upload/limits` | ❌ Public | Limites d'upload |
| `GET` | `/api/v1/upload/validate-type` | ❌ Public | Valider type de fichier |

---

## 📋 13. AUDIT & LOGS

### 13.1 Audit Logs

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/audit/logs` | ✅ Protected | Rechercher dans les logs |
| `GET` | `/api/v1/audit/logs/:id` | ✅ Protected | Détails d'un log |
| `GET` | `/api/v1/audit/stats` | ✅ Protected | Statistiques d'audit |
| `GET` | `/api/v1/audit/activity` | ✅ Protected | Activité utilisateur |
| `GET` | `/api/v1/audit/suspicious` | ✅ Protected | Détecter activité suspecte |
| `GET` | `/api/v1/audit/ip/:ip` | ✅ Protected | Activité par IP |
| `POST` | `/api/v1/audit/cleanup` | ✅ Protected | Nettoyer anciens logs |

---

## 🔒 14. SECURITY

### 14.1 CSRF Token

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/csrf-token` | ✅ Protected | Obtenir token CSRF |

---

## 📝 15. FRONTEND LOGS

### 15.1 Frontend Logging

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/logs/frontend` | ❌ Public | Envoyer logs frontend au backend |

---

## 🏥 16. HEALTH & MONITORING

### 16.1 Health Checks

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/health` | ❌ Public | Health check simple |
| `GET` | `/api/v1/healthz` | ❌ Public | Liveness probe (Kubernetes) |
| `GET` | `/api/v1/readyz` | ❌ Public | Readiness probe (Kubernetes) |
| `GET` | `/api/v1/status` | ❌ Public | Status complet du système |

**Legacy (deprecated):**
- `GET /health`
- `GET /healthz`
- `GET /readyz`

---

### 16.2 Metrics

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/metrics` | ❌ Public | Métriques Prometheus |
| `GET` | `/api/v1/metrics/aggregated` | ❌ Public | Métriques agrégées |
| `GET` | `/api/v1/system/metrics` | ❌ Public | Métriques système |

**Legacy (deprecated):**
- `GET /metrics`
- `GET /metrics/aggregated`
- `GET /system/metrics`

---

### 16.3 API Versioning

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/versions` | ❌ Public | Informations sur les versions API |

---

## 👨‍💼 17. ADMIN ENDPOINTS

### 17.1 Admin Audit

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/api/v1/admin/audit/logs` | ✅ Admin | Logs d'audit (admin) |
| `GET` | `/api/v1/admin/audit/stats` | ✅ Admin | Statistiques d'audit (admin) |
| `GET` | `/api/v1/admin/audit/suspicious` | ✅ Admin | Activité suspecte (admin) |

---

### 17.2 Admin Debugging

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `ANY` | `/api/v1/admin/debug/pprof/*path` | ✅ Admin | Profiling pprof (Go) |

---

## 🔧 18. INTERNAL ENDPOINTS

### 18.1 Stream Callbacks

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `POST` | `/api/v1/internal/tracks/:id/stream-ready` | 🔒 Internal | Callback stream ready (moderne) |
| `POST` | `/internal/tracks/:id/stream-ready` | 🔒 Internal | Callback stream ready (legacy, deprecated) |

---

## 📚 19. DOCUMENTATION

### 19.1 API Documentation

| Méthode | Endpoint | Auth | Description |
|---------|----------|------|-------------|
| `GET` | `/swagger/*any` | ❌ Public | Documentation Swagger UI |
| `GET` | `/docs` | ❌ Public | Documentation API (alias) |
| `GET` | `/docs/*any` | ❌ Public | Documentation API (alias) |

---

## 📊 RÉSUMÉ PAR CATÉGORIE

| Catégorie | Endpoints | Public | Protected | Admin |
|-----------|-----------|--------|-----------|-------|
| **Auth** | 17 | 12 | 5 | 0 |
| **Users** | 15 | 4 | 11 | 0 |
| **Tracks** | 35 | 10 | 25 | 0 |
| **Playlists** | 13 | 0 | 13 | 0 |
| **Marketplace** | 6 | 1 | 5 | 0 |
| **Chat** | 8 | 0 | 8 | 0 |
| **Notifications** | 3 | 0 | 3 | 0 |
| **Roles** | 2 | 0 | 2 | 0 |
| **Webhooks** | 6 | 0 | 6 | 0 |
| **Analytics** | 2 | 0 | 2 | 0 |
| **Sessions** | 6 | 0 | 6 | 0 |
| **Uploads** | 8 | 2 | 6 | 0 |
| **Audit** | 7 | 0 | 7 | 0 |
| **Security** | 1 | 0 | 1 | 0 |
| **Logs** | 1 | 1 | 0 | 0 |
| **Health** | 7 | 7 | 0 | 0 |
| **Admin** | 4 | 0 | 0 | 4 |
| **Internal** | 2 | 0 | 0 | 2 |
| **Docs** | 3 | 3 | 0 | 0 |
| **TOTAL** | **145** | **40** | **101** | **4** |

---

## 🔐 AUTHENTIFICATION & AUTORISATION

### Types d'Authentification

1. **❌ Public** - Aucune authentification requise
2. **✅ Protected** - JWT token requis
3. **✅ Owner/Admin** - JWT + ownership ou rôle admin
4. **✅ Creator/Premium/Admin** - JWT + rôle spécifique
5. **✅ Admin** - JWT + rôle admin uniquement
6. **🔒 Internal** - Endpoints internes (callbacks)

### Middlewares Appliqués

- **CORS** - Configuré via `CORS_ORIGINS`
- **CSRF** - Protection sur tous les POST/PUT/DELETE (nécessite Redis)
- **Rate Limiting** - Limites globales + endpoints spécifiques
- **Timeout** - Timeout global configurable
- **Security Headers** - HSTS, CSP, etc.
- **Request ID** - Traçabilité des requêtes
- **Metrics** - Prometheus metrics
- **Logging** - Structured logging
- **Error Handling** - Gestion centralisée des erreurs

---

## 🚀 FEATURES SPÉCIALES

### Rate Limiting

**Endpoints avec rate limiting spécifique:**
- `/api/v1/auth/register` - Limité
- `/api/v1/auth/login` - Limité
- `/api/v1/auth/verify-email` - Limité
- `/api/v1/auth/resend-verification` - Limité
- `/api/v1/auth/password/*` - Limité
- `/api/v1/uploads/*` - Limité (Redis requis)

### CSRF Protection

**Tous les endpoints avec méthodes:**
- `POST`
- `PUT`
- `DELETE`
- `PATCH`

**Exceptions:**
- Endpoints publics
- `/api/v1/csrf-token` (génération du token)

### Chunked Upload

**Support pour gros fichiers:**
1. `POST /api/v1/tracks/initiate` - Initier
2. `POST /api/v1/tracks/chunk` - Upload chunks
3. `POST /api/v1/tracks/complete` - Finaliser

### ClamAV Scanning

**Scan antivirus sur uploads:**
- Configurable via `ENABLE_CLAMAV`
- Configurable via `CLAMAV_REQUIRED`
- Appliqué sur tous les uploads de fichiers

---

## 📝 NOTES IMPORTANTES

### Versioning

- **Version actuelle**: `v1`
- **Base path**: `/api/v1`
- **Legacy paths**: Certains endpoints ont des versions deprecated (ex: `/health` → `/api/v1/health`)

### Deprecation

**Endpoints deprecated (avec warning):**
- `/health` → `/api/v1/health`
- `/healthz` → `/api/v1/healthz`
- `/readyz` → `/api/v1/readyz`
- `/metrics` → `/api/v1/metrics`
- `/internal/tracks/:id/stream-ready` → `/api/v1/internal/tracks/:id/stream-ready`

### Pagination

**Endpoints paginés:**
- `/api/v1/users`
- `/api/v1/tracks`
- `/api/v1/playlists`
- `/api/v1/marketplace/products`
- `/api/v1/marketplace/orders`
- `/api/v1/notifications`
- `/api/v1/audit/logs`

**Paramètres de pagination:**
- `page` - Numéro de page (défaut: 1)
- `limit` - Nombre d'éléments par page (défaut: 20)
- `sort` - Champ de tri
- `order` - Ordre (asc/desc)

### Filtrage

**Endpoints avec filtres:**
- `/api/v1/tracks` - Genre, tags, date, duration
- `/api/v1/users/search` - Query, role
- `/api/v1/tracks/search` - Query, genre, tags
- `/api/v1/playlists/search` - Query, public/private
- `/api/v1/marketplace/products` - Category, price range, seller

---

## 🔍 ENDPOINTS PAR MÉTHODE HTTP

### GET (Lecture)
- **Total**: 75 endpoints
- **Catégories**: Users, Tracks, Playlists, Marketplace, Health, etc.

### POST (Création)
- **Total**: 45 endpoints
- **Catégories**: Auth, Tracks, Playlists, Orders, Chat, etc.

### PUT (Mise à jour complète)
- **Total**: 10 endpoints
- **Catégories**: Users, Tracks, Playlists, Conversations

### DELETE (Suppression)
- **Total**: 15 endpoints
- **Catégories**: Users, Tracks, Playlists, Sessions, Webhooks

---

## 🎯 ENDPOINTS PRIORITAIRES POUR FRONTEND

### P0 - Critique (MVP)

**Auth:**
- `POST /api/v1/auth/register`
- `POST /api/v1/auth/login`
- `POST /api/v1/auth/logout`
- `GET /api/v1/auth/me`

**Users:**
- `GET /api/v1/users/:id`
- `PUT /api/v1/users/:id`

**Tracks:**
- `GET /api/v1/tracks`
- `GET /api/v1/tracks/:id`
- `POST /api/v1/tracks`
- `POST /api/v1/tracks/:id/like`

**Playlists:**
- `GET /api/v1/playlists`
- `POST /api/v1/playlists`
- `POST /api/v1/playlists/:id/tracks`

### P1 - Important

**Search:**
- `GET /api/v1/tracks/search`
- `GET /api/v1/users/search`

**Upload:**
- `POST /api/v1/tracks/initiate`
- `POST /api/v1/tracks/chunk`
- `POST /api/v1/tracks/complete`

**Notifications:**
- `GET /api/v1/notifications`
- `POST /api/v1/notifications/:id/read`

### P2 - Souhaitable

**Marketplace:**
- `GET /api/v1/marketplace/products`
- `POST /api/v1/marketplace/orders`

**Analytics:**
- `POST /api/v1/analytics/events`
- `GET /api/v1/analytics/tracks/:id`

**Webhooks:**
- `GET /api/v1/webhooks`
- `POST /api/v1/webhooks`

---

## 📖 DOCUMENTATION COMPLÈTE

Pour plus de détails sur chaque endpoint:
- **Swagger UI**: `/swagger/index.html`
- **Docs**: `/docs`
- **OpenAPI Spec**: Disponible via Swagger

---

**Version**: 1.0.0  
**Dernière mise à jour**: 2026-01-05  
**Auteur**: Veza Backend Team