Story 3.4: Créer l'endpoint API pour récupérer les prédictions

Status: review

Acceptance Criteria

Given des prédictions existent dans la base de données When je fais une requête GET /api/v1/predictions Then je reçois une liste de prédictions avec match, confidence, équipe prédite And les prédictions sont triées par date de match (prochaines en premier) And la réponse est au format JSON avec structure standardisée

Given je fais une requête pour un match spécifique When je fais GET /api/v1/predictions/{match_id} Then je reçois les détails complets de la prédiction And la réponse inclut l'énergie collective, confidence, historique

Tasks / Subtasks

Créer l'endpoint GET /predictions (AC: #1)
- Créer GET /api/v1/predictions
- Récupérer toutes les prédictions depuis la base de données
- Joindre avec les données des matchs
- Trier par date de match (prochaines en premier)
- Retourner la liste avec pagination
Créer l'endpoint GET /predictions/{match_id} (AC: #2)
- Créer GET /api/v1/predictions/{match_id}
- Récupérer la prédiction spécifique
- Inclure les détails complets (match, énergie, historique)
- Retourner 404 si la prédiction n'existe pas
- Formater la réponse standardisée
Créer les schémas Pydantic pour les réponses (AC: #1, #2)
- Créer PredictionResponse schema
- Créer PredictionListResponse schema
- Inclure les champs: match, confidence, predicted_winner
- Valider les types et formats
- Documenter les schémas
Implémenter la pagination et filtres (AC: #1)
- Ajouter les query parameters: limit, offset
- Ajouter les filtres optionnels: team_id, league, date_min, date_max
- Valider les paramètres avec Pydantic
- Appliquer les filtres aux requêtes de base de données
- Retourner les métadonnées de pagination
Optimiser les requêtes de base de données (AC: #1)
- Créer les indexes appropriés sur predictions
- Optimiser les JOINs avec matches
- Implémenter le caching si nécessaire
- Valider les performances avec 1000+ prédictions
- Monitorer les temps de réponse
Documenter les endpoints avec Swagger (AC: #1, #2)
- Ajouter les descriptions détaillées des endpoints
- Ajouter les exemples de requêtes/réponses
- Documenter les query parameters
- Ajouter les codes d'erreur possibles
- Valider la documentation Swagger UI
Tester les endpoints API (AC: #1, #2)
- Tester GET /predictions sans filtres
- Tester GET /predictions avec pagination
- Tester GET /predictions avec filtres
- Tester GET /predictions/{match_id}
- Valider le format de réponse standardisé
- Tester les codes d'erreur (404, 400)

Dev Notes

Architecture Patterns

Stack Technique:

API: FastAPI
Validation: Pydantic
Documentation: OpenAPI 3.1 (Swagger UI)
Pagination: Query parameters (limit, offset)
Format: JSON standardisé {data, meta}

Endpoint Implementation

from fastapi import APIRouter, Query, HTTPException
from typing import Optional

router = APIRouter(prefix="/api/v1", tags=["predictions"])

@router.get("/predictions", response_model=PredictionListResponse)
async def get_predictions(
    limit: int = Query(20, le=100),
    offset: int = Query(0, ge=0),
    team_id: Optional[int] = None,
    league: Optional[str] = None
):
    # Récupérer les prédictions avec pagination et filtres
    predictions = get_predictions_from_db(limit, offset, team_id, league)
    
    # Formatter la réponse standardisée
    return {
        "data": predictions,
        "meta": {
            "total": len(predictions),
            "limit": limit,
            "offset": offset,
            "timestamp": datetime.now().isoformat(),
            "version": "v1"
        }
    }

@router.get("/predictions/{match_id}", response_model=PredictionResponse)
async def get_prediction_by_id(match_id: int):
    prediction = get_prediction_by_id_from_db(match_id)
    
    if not prediction:
        raise HTTPException(status_code=404, detail="Prediction not found")
    
    return {
        "data": prediction,
        "meta": {
            "timestamp": datetime.now().isoformat(),
            "version": "v1"
        }
    }

File Structure

backend/app/api/v1/
└── predictions.py
backend/app/schemas/
└── prediction.py

References

[Source: _bmad-output/planning-artifacts/epics.md#Story-3.4]

Dev Agent Record

Agent Model Used

GLM-4.7

Completion Notes List

✅ Schémas Pydantic mis à jour avec MatchInfo et PredictionListMeta
✅ Méthodes de service implémentées: get_predictions_with_pagination et get_prediction_with_details
✅ Endpoint GET /api/v1/predictions créé avec pagination (limit, offset) et filtres (team_id, league, date_min, date_max)
✅ Endpoint GET /api/v1/predictions/match/{match_id} créé avec détails complets (match, énergie, historique)
✅ Documentation Swagger complète ajoutée avec exemples de requêtes/réponses
✅ Tests unitaires étendus pour couvrir tous les nouveaux cas (TestGetPredictionsEndpoint, TestGetPredictionByMatchIdEndpoint)
✅ Réponses standardisées au format {data, meta} avec timestamp et version
✅ Optimisation avec jointures SQL et tri par date de match

File List

backend/app/api/v1/predictions.py (modifié)
backend/app/schemas/prediction.py (modifié)
backend/app/services/prediction_service.py (modifié)
backend/tests/test_prediction_api.py (modifié)

5.6 KiB Raw Blame History