veza/docs/archive/root-md/BACKEND_ENDPOINTS_EXHAUSTIVE_LIST.md
senke 43af35fd93 chore(audit 2.2, 2.3): nettoyer .md et .json à la racine
- Archiver 131 .md dans docs/archive/root-md/
- Archiver 22 .json dans docs/archive/root-json/
- Conserver 7 .md utiles (README, CONTRIBUTING, CHANGELOG, etc.)
- Conserver package.json, package-lock.json, turbo.json
- Ajouter README d'index dans chaque archive
2026-02-15 14:35:08 +01:00

25 KiB

🔌 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

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