Partie I : Consommation des API

Guide complet pour developpeurs - Comment consommer efficacement l'API MyTelevision v2.0

Table des matieres

Documentation Swagger/OpenAPI
Authentification & Securite
Bonnes pratiques de consommation d'API

1. Documentation Swagger/OpenAPI

1.1 Comment acceder a Swagger

URLs d'acces

La documentation interactive Swagger/OpenAPI est accessible aux URLs suivantes :

Environnement	URL
Local (developpement)	`http://localhost:3000/api/docs`
Staging	`https://staging-api.mytelevision.app/api/docs`
Production	`https://api.mytelevision.app/api/docs`

Interface Swagger UI

L'interface Swagger UI offre une documentation interactive complete de l'API avec les fonctionnalites suivantes :

Try it out : Testez directement les endpoints depuis le navigateur
- Cliquez sur un endpoint puis "Try it out", remplissez les parametres, puis "Execute"
- Visualisez la requete curl generee et la reponse en temps reel
Models/Schemas : Documentation complete des structures de donnees
- Schemas de requete (DTOs d'entree)
- Schemas de reponse (formats de retour)
- Validation des champs et contraintes
Authorize : Authentification centralisee
- Bouton "Authorize" en haut a droite
- Entrez votre token JWT : Bearer <votre_access_token>
- Le token est automatiquement ajoute a toutes les requetes
Fonctionnalites avancees :
- Filter : Recherche rapide d'endpoints par mot-cle
- Display duration : Temps de reponse affiche pour chaque requete
- Syntax highlighting : Coloration syntaxique JSON (theme Monokai)
- Persist authorization : Le token reste en memoire lors de la navigation

1.2 Structure generale

L'API MyTelevision suit une architecture organisee par tags (modules fonctionnels) avec une separation claire entre les endpoints publics (Client) et administratifs (Admin).

Les endpoints sont regroupes en 41 controleurs organises en 2 categories principales :

Endpoints Client (API publique `/api/v2/...`)

Accessibles aux applications front-end et mobiles. Authentification JWT requise pour la plupart (sauf /auth/* et /health/*).

Endpoints Admin (Panel d'administration `/api/v2/admin/...`)

Accessibles uniquement aux utilisateurs avec roles ADMIN, MODERATOR ou SUPER_ADMIN. Authentification JWT obligatoire.

1.3 Organisation des modules

Modules Client (22 controleurs)

Tag	Description	Endpoints cles
Auth	Authentication - Login, Register, Password reset, Token refresh	`POST /auth/login`, `POST /auth/register`, `GET /auth/me`
Users	User management - Profile, Devices, Sessions	`GET /users/profile`, `PUT /users/profile`
Movies	Movies - Browse, Search, Featured, Top 10, Details	`GET /movies`, `GET /movies/{id}`, `GET /movies/featured`
Series	TV Series - Seasons, Episodes, Browse, Search	`GET /series`, `GET /series/{id}/seasons`
Live TV	Live TV channels - Browse by category, Featured channels	`GET /livetv/channels`, `GET /livetv/categories`
Radio	Radio stations - Browse, Featured, Categories	`GET /radio/channels`, `GET /radio/featured`
Podcasts	Podcasts - Collections, Episodes, Categories	`GET /podcasts`, `GET /podcasts/{id}/episodes`
Live Events	Live events and sports - Upcoming, Live now	`GET /live-events`, `GET /live-events/live-now`
News	News articles - Browse, Categories, Recent	`GET /news`, `GET /news/recent`
Catalog	Genres and Categories - Browse content taxonomy	`GET /catalog/genres`, `GET /catalog/categories`
Favorites	User favorites - Add, Remove, List by media type	`POST /favorites`, `GET /favorites`, `DELETE /favorites/{id}`
Watch History	User watch history - Track progress, Resume playback	`POST /watch-history`, `GET /watch-history`
Notifications	Push notifications - List, Mark read, Delete	`GET /notifications`, `PUT /notifications/{id}/read`
Support	Support tickets - Create, Reply, View status	`POST /support/tickets`, `GET /support/tickets`
Settings	Application settings - Public configuration	`GET /settings`
Sliders	Promotional sliders - Homepage banners	`GET /sliders`
Banners	Advertising banners - Display ads	`GET /banners`
Subscription Plans	Subscription plans - Pricing, Features	`GET /subscription-plans`
Countries	Countries reference data	`GET /countries`
Languages	Languages reference data	`GET /languages`
Streaming	Streaming security - Token generation, Signed URLs, DRM	`POST /streaming/generate-token`
Health	Health check endpoints - API status, Database, Redis	`GET /health`, `GET /health/live`, `GET /health/ready`

Modules Admin (19 controleurs)

Tag	Description	Endpoints cles
Admin - Authentication	Admin authentication - Login, Sessions	`POST /admin/auth/login`, `GET /admin/auth/me`
Admin - Users	Admin user management - CRUD, Roles, Status	`GET /admin/users`, `PUT /admin/users/{id}/role`
Admin - Movies	Admin movies management - CRUD, TMDb auto-fill	`POST /admin/movies`, `POST /admin/movies/tmdb/import`
Admin - Series	Admin series management - CRUD, Seasons, Episodes	`POST /admin/series`, `POST /admin/series/{id}/seasons`
Admin - Live TV	Admin Live TV management - Channels, Categories	`POST /admin/livetv/channels`
Admin - Radio	Admin radio management - Channels, Categories	`POST /admin/radio/channels`
Admin - Podcasts	Admin podcasts management - Collections, Episodes, Podcasters	`POST /admin/podcasts`
Admin - Live Events	Admin live events management - CRUD, Categories	`POST /admin/live-events`
Admin - News	Admin news management - Articles, Categories	`POST /admin/news`
Admin - Catalog	Admin catalog management - Genres, Categories	`POST /admin/catalog/genres`
Admin - Settings	Admin settings management - All configuration groups	`PUT /admin/settings/{key}`
Admin - Sliders	Admin sliders management - CRUD, Scheduling	`POST /admin/sliders`
Admin - Banners	Admin banners management - CRUD, Analytics	`POST /admin/banners`
Admin - Subscription Plans	Admin subscription plans management - CRUD	`POST /admin/subscription-plans`
Admin - RBAC	Role-Based Access Control - Roles, Permissions	`GET /admin/rbac/roles`
Admin - Support	Admin support management - Tickets, Reply	`GET /admin/support/tickets`
Admin - Notifications	Admin notifications - Broadcast, Send, Schedule	`POST /admin/notifications/broadcast`
Admin - Countries	Admin countries management	`POST /admin/countries`
Admin - Languages	Admin languages management	`POST /admin/languages`

2. Authentification & Securite

2.1 JWT - Tokens d'acces

Flux d'authentification

Durees de validite

Token	Duree	Renouvellement
Access Token	1 heure	Via refresh token
Refresh Token	7 jours	Rotation automatique

# Login
curl -X POST https://api.mytelevision.app/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123"
  }'

# Reponse
{
  "tokens": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  },
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "role": "USER"
  }
}

Refresh Token

curl -X POST https://api.mytelevision.app/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiIs..."}'

2.2 Sessions utilisateur

Chaque login cree une session unique liee a l'appareil
Utilisez le header X-Device-Id pour identifier l'appareil client
Les sessions peuvent etre listees et revoquees individuellement

# Lister les sessions actives
curl -X GET https://api.mytelevision.app/api/v2/auth/sessions \
  -H "Authorization: Bearer $TOKEN"

# Revoquer une session
curl -X DELETE https://api.mytelevision.app/api/v2/auth/sessions/{sessionId} \
  -H "Authorization: Bearer $TOKEN"

2.3 RBAC - Roles et Permissions

Hierarchie des roles

SUPER_ADMIN > ADMIN > MODERATOR > USER
     |          |          |         |
     |          |          |         +-- Lecture contenu, favoris, historique
     |          |          +-- + Moderation contenu (CRUD partiel)
     |          +-- + Gestion utilisateurs, settings
     +-- + Tous les droits, RBAC, logs systeme

Acces aux endpoints

Role	Endpoints Client	Endpoints Admin
USER	Tous	Aucun
MODERATOR	Tous	CRUD contenu partiel
ADMIN	Tous	Tous sauf RBAC
SUPER_ADMIN	Tous	Tous

2.4 Streaming Security

# 1. Generer un token de streaming
curl -X POST https://api.mytelevision.app/api/v2/streaming/generate-token \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contentId": "movie-uuid", "mediaType": "MOVIE"}'

# Reponse
{
  "streamToken": "st_abc123...",
  "streamUrl": "https://cdn.../movie.m3u8?token=st_abc123...",
  "expiresAt": "2025-01-15T11:00:00Z"
}

Mecanisme	Description
Token binding	Token lie a l'IP du client et au referer
Expiration	TTL configurable (defaut: 1h)
Usage limit	Nombre d'utilisations max (defaut: 1)
DRM AES-128	Chiffrement des flux HLS
Anti-hotlink	Validation du referer HTTP

2.5 Erreurs frequentes et resolutions

Code	Erreur	Cause	Resolution
401	Unauthorized	Token expire ou invalide	Refresher le token
403	Forbidden	Permission insuffisante	Verifier le role utilisateur
429	Too Many Requests	Rate limit depasse	Attendre et reessayer avec backoff

2.6 Bonnes pratiques de securite

Ne jamais exposer les tokens dans les URLs ou logs
Implementer l'auto-refresh des tokens cote client
Stocker les tokens en memoire ou secure storage (pas localStorage)
Utiliser HTTPS pour toutes les requetes en staging/production
Gerer la deconnexion en revoquant la session cote serveur
Implementer le retry avec backoff exponentiel pour les 429

3. Bonnes pratiques de consommation d'API

3.1 Pagination standardisee

Toutes les listes paginees utilisent le meme format :

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Parametres de pagination :

page : Numero de page (defaut: 1)
limit : Elements par page (defaut: 20, max: 100)

3.2 Format d'erreur standardise

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "email",
      "message": "email must be a valid email address"
    }
  ]
}

3.3 Internationalisation

L'API supporte deux locales :

Locale	Langue	Defaut
`fr_FR`	Francais (France)	Oui
`en_US`	English (United States)	Non

Detection de la locale (par priorite) :

Query Parameter : ?lang=en_US
Header : Accept-Language: en-US,en;q=0.9,fr;q=0.8
Defaut : fr_FR

3.4 Optimisation et performance

Cache Redis : Les reponses GET sont cachees (TTL 5 minutes)
Compression gzip : Envoyez Accept-Encoding: gzip
Pagination : Ne demandez que les donnees necessaires
Filtres : Utilisez les query params pour filtrer cote serveur

3.5 Checklist developpeur

Avant d'integrer l'API

Lire la documentation Swagger (/api/docs)
Configurer les variables d'environnement
Tester GET /health pour verifier la connectivite
Implementer le flux d'authentification JWT
Mettre en place l'auto-refresh des tokens
Gerer les erreurs (401, 403, 429, 500)

Avant la mise en production

Utiliser les URLs de production (https://api.mytelevision.app)
Verifier que HTTPS est utilise partout
Implementer le rate limiting cote client
Tester la gestion des erreurs reseau
Valider les schemas de reponse

Changelog

Version	Date	Modifications
1.0.0	2025-12-12	Version initiale Partie I

Derniere mise a jour : 12 decembre 2025 Auteurs : Equipe MyTelevision + Claude Code AI

Table des matieres​

1. Documentation Swagger/OpenAPI​

1.1 Comment acceder a Swagger​

URLs d'acces​

Interface Swagger UI​

1.2 Structure generale​

Endpoints Client (API publique /api/v2/...)​

Endpoints Admin (Panel d'administration /api/v2/admin/...)​

1.3 Organisation des modules​

Modules Client (22 controleurs)​

Modules Admin (19 controleurs)​

2. Authentification & Securite​

2.1 JWT - Tokens d'acces​

Flux d'authentification​

Durees de validite​

Exemple de login​

Refresh Token​

2.2 Sessions utilisateur​

2.3 RBAC - Roles et Permissions​

Hierarchie des roles​

Acces aux endpoints​

2.4 Streaming Security​

2.5 Erreurs frequentes et resolutions​

2.6 Bonnes pratiques de securite​

3. Bonnes pratiques de consommation d'API​

3.1 Pagination standardisee​

3.2 Format d'erreur standardise​

3.3 Internationalisation​

3.4 Optimisation et performance​

3.5 Checklist developpeur​

Avant d'integrer l'API​

Avant la mise en production​

Changelog​