Skip to content

API_SPECIFICATIONS.md

Latest commit

 

History

History
528 lines (413 loc) · 11 KB

API_SPECIFICATIONS.md

File metadata and controls

528 lines (413 loc) · 11 KB
Raw

Spécifications API — DataNova

Version : 1.0.0
Base URL : http://localhost:8000/api/v1
Format : JSON (REST)
Authentification : JWT Bearer Token

Table des Matières

  1. Authentification
  2. Utilisateurs
  3. Datasets
  4. Pipelines
  5. Analyse & Visualisation
  6. Modèles ML
  7. Recommandations
  8. Expériences
  9. Prédictions
  10. Rapports
  11. Activités
  12. Logs Système

1. Authentification

POST /api/v1/auth/register

Inscription d'un nouvel utilisateur.

Body :

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "full_name": "John Doe"
}

Response : 201 Created

{
  "id": "uuid",
  "email": "user@example.com",
  "is_active": true
}

POST /api/v1/auth/jwt/login

Connexion (form-data).

Body : username=user@example.com&password=SecurePass123!

Response : 200 OK

{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

POST /api/v1/auth/jwt/refresh

Rafraîchir le token JWT.

POST /api/v1/auth/jwt/logout

Déconnexion.

2. Utilisateurs

GET /api/v1/users/me

Profil de l'utilisateur connecté.
Auth : Required

PATCH /api/v1/users/me

Mettre à jour son profil.
Auth : Required

PATCH /api/v1/users/me/ai-config

Configurer la clé API Groq.

Body :

{
  "groq_api_key": "gsk_..."
}

POST /api/v1/users/me/change-password

Changer le mot de passe.

Body :

{
  "current_password": "old",
  "new_password": "NewSecure456!",
  "confirm_password": "NewSecure456!"
}

GET /api/v1/users (Superuser only)

Lister tous les utilisateurs.

3. Datasets

POST /api/v1/datasets/

Uploader un fichier CSV.

Content-Type : multipart/form-data
Param : file (CSV uniquement)

Response : 201 Created

{
  "id": "uuid",
  "filename": "data.csv",
  "file_path": "uploads/uuid.csv",
  "file_size": 12345,
  "columns": [{"name": "age", "type": "int64"}, {"name": "salary", "type": "float64"}],
  "row_count": 1000,
  "created_at": "2026-07-21T00:00:00Z"
}

GET /api/v1/datasets/

Lister les datasets de l'utilisateur.
Auth : Required
Response : List[DatasetRead]

GET /api/v1/datasets/{dataset_id}

Détails d'un dataset (inclut colonnes, types).
Auth : Required (propriétaire)

DELETE /api/v1/datasets/{dataset_id}

Supprimer un dataset et son fichier physique.
Auth : Required (propriétaire)
Cascade : Pipelines → Experiments
Response : 204 No Content

4. Pipelines

POST /api/v1/pipelines/

Créer un pipeline de preprocessing.

Body :

{
  "dataset_id": "uuid",
  "name": "Mon Pipeline",
  "description": "Nettoyage + normalisation",
  "steps": [
    {"operation": "drop", "params": {"columns": ["id"]}},
    {"operation": "fill_missing", "params": {"strategy": "mean"}},
    {"operation": "scale", "params": {"method": "standard"}}
  ]
}

Response : 201 Created

POST /api/v1/pipelines/preview

Prévisualiser un pipeline sur 10 lignes.

Body :

{
  "dataset_id": "uuid",
  "steps": [{"operation": "drop", "params": {"columns": ["id"]}}]
}

Response :

{
  "preview": [{"age": 25, "salary": 50000}, ...],
  "columns": ["age", "salary"],
  "column_types": {"age": "num", "salary": "num"}
}

GET /api/v1/pipelines/

Lister les pipelines. Filtrage optionnel par dataset_id.
Auth : Required

GET /api/v1/pipelines/{pipeline_id}

Détails d'un pipeline.

PUT /api/v1/pipelines/{pipeline_id}

Mettre à jour un pipeline (nom, description, steps).

DELETE /api/v1/pipelines/{pipeline_id}

Supprimer un pipeline.
Response : 204 No Content

5. Analyse & Visualisation

Tous les endpoints retournent des images PNG (image/png).

GET /api/v1/analysis/{dataset_id}/distribution?column=age

Histogramme / distribution d'une colonne.

GET /api/v1/analysis/{dataset_id}/correlation

Heatmap de corrélation (toutes les colonnes numériques).

GET /api/v1/analysis/{dataset_id}/scatter?x=age&y=salary

Nuage de points (scatter plot).

GET /api/v1/analysis/{dataset_id}/missing-values

Graphique des valeurs manquantes.

GET /api/v1/analysis/{dataset_id}/histograms?columns=age,salary&bins=30

Histogrammes multiples.

GET /api/v1/analysis/{dataset_id}/boxplot?columns=age,salary

Boxplots pour détection d'outliers.

GET /api/v1/analysis/{dataset_id}/categorical-distribution?max_categories=20

Distribution des variables catégorielles.

GET /api/v1/analysis/{dataset_id}/pca?n_components=2

Projection PCA (réduction de dimensionnalité).

GET /api/v1/analysis/{dataset_id}/tsne?perplexity=30

Projection t-SNE (max 1000 échantillons).

GET /api/v1/analysis/{dataset_id}/pie-chart?column=category&max_categories=10

Diagramme circulaire pour colonne catégorielle.

6. Modèles ML

GET /api/v1/ml/models/

Liste de tous les modèles ML disponibles par catégorie.

Response :

{
  "classification": [
    {"name": "random_forest_classifier", "display_name": "Random Forest", ...}
  ],
  "regression": [...],
  "clustering": [...]
}

GET /api/v1/ml/models/{category}

Modèles par catégorie (classification, regression, clustering).

GET /api/v1/ml/models/{algorithm}/schema?task_type=classification

Schéma des hyperparamètres d'un algorithme.

Response :

{
  "algorithm": "random_forest_classifier",
  "display_name": "Random Forest Classifier",
  "hyperparameters": {
    "n_estimators": {"type": "int", "default": 100, "min": 10, "max": 1000},
    "max_depth": {"type": "int", "default": null, "min": 1, "max": 100}
  }
}

GET /api/v1/ml/models/{algorithm}/metadata

Métadonnées d'un algorithme.

7. Recommandations

POST /api/v1/recommendations/generate

Générer des recommandations d'algorithmes.

Body :

{
  "dataset_id": "uuid",
  "problem_type": "classification"
}

Response :

{
  "dataset_id": "uuid",
  "recommendations": [
    {
      "algorithm": "random_forest_classifier",
      "display_name": "Random Forest",
      "score": 92.5,
      "reasons": ["Handles mixed data types", "Robust to outliers"],
      "warnings": ["May overfit on very small datasets"]
    }
  ],
  "problem_type": "classification",
  "dataset_profile": {...}
}

POST /api/v1/recommendations/{dataset_id}?top_k=5&force_reanalyze=false

Recommandations détaillées avec analyse complète.

POST /api/v1/recommendations/feedback/{recommendation_id}

Soumettre un feedback sur une recommandation.

Body :

{
  "rating": 4,
  "was_used": true,
  "actual_metrics": {"accuracy": 0.94},
  "comment": "Bon choix pour ce dataset"
}

8. Expériences

POST /api/v1/experiments/

Lancer un entraînement ML.

Body :

{
  "name": "Classification RF",
  "pipeline_id": "uuid",
  "task_type": "classification",
  "target_column": "target",
  "algorithm": "random_forest_classifier",
  "hyperparameters": {"n_estimators": 100, "max_depth": 10},
  "splitting_config": {
    "method": "random",
    "test_size": 0.2,
    "shuffle": true,
    "stratify": true
  }
}

Response : 202 Accepted

{
  "id": "uuid",
  "status": "PENDING",
  "message": "Training initiated"
}

GET /api/v1/experiments/

Lister toutes les expériences de l'utilisateur.

GET /api/v1/experiments/{id}

Statut et résultats d'une expérience.

Response (COMPLETED) :

{
  "id": "uuid",
  "name": "Classification RF",
  "status": "COMPLETED",
  "metrics": {
    "accuracy": 0.945,
    "precision": 0.94,
    "recall": 0.93,
    "f1_score": 0.935
  },
  "model_path": "models/uuid.joblib"
}

DELETE /api/v1/experiments/{id}

Supprimer une expérience.
Response : 204 No Content

GET /api/v1/experiments/{id}/download-model

Télécharger le modèle entraîné (fichier .joblib).

9. Prédictions

POST /api/v1/predictions/{experiment_id}

Prédiction unitaire.

Body :

{
  "features": {"age": 35, "salary": 75000, "department": "Engineering"}
}

Response :

{
  "prediction": "Yes",
  "probabilities": [0.15, 0.85],
  "experiment_id": "uuid",
  "model_type": "classification"
}

POST /api/v1/predictions/{experiment_id}/batch

Prédiction par lot.

Body :

{
  "samples": [
    {"age": 35, "salary": 75000},
    {"age": 42, "salary": 82000}
  ]
}

GET /api/v1/predictions/{experiment_id}/info

Informations sur le modèle (métriques, configuration).

DELETE /api/v1/predictions/{experiment_id}/cache

Vider le cache d'un modèle spécifique.

DELETE /api/v1/predictions/cache/all

Vider tous les caches de modèles.

10. Rapports

POST /api/v1/reports/generate

Générer un rapport PDF pour une expérience.

Body :

{
  "experiment_id": "uuid",
  "include_dataset_analysis": true,
  "include_pipeline_details": true,
  "include_visualizations": true
}

Response :

{
  "report_id": "uuid",
  "file_path": "reports/experiment_report_uuid.pdf",
  "file_size_bytes": 245678,
  "generated_at": "2026-07-21T00:00:00Z",
  "experiment_name": "Classification RF"
}

GET /api/v1/reports/{report_id}/download?file_path=reports/experiment_report_uuid.pdf

Télécharger le rapport PDF.

11. Activités

GET /api/v1/activities

Activités de l'utilisateur (avec filtres).

Query Parameters :

Param Type Description
user_id UUID Filtrer par utilisateur (superuser)
action_type string create, update, delete, view, download, login, etc.
resource_type string dataset, pipeline, experiment, report, etc.
start_date datetime Date de début
end_date datetime Date de fin
limit int Nombre résultats (1-1000, défaut 100)
offset int Pagination (défaut 0)

GET /api/v1/activities/stats

Statistiques d'activité agrégées.

GET /api/v1/activities/recent

Activités récentes (10 dernières).

12. Logs Système

GET /api/v1/logs/

Logs système (superuser uniquement).

Query Parameters :

Param Type Description
skip int Offset (défaut 0)
limit int Nombre résultats (défaut 50)
level string INFO, WARNING, ERROR

Codes d'Erreur Communs

Code Signification
200 Succès
201 Créé
202 Accepté (traitement asynchrone)
204 Succès sans contenu (delete)
400 Requête invalide
401 Non authentifié
403 Accès refusé (pas propriétaire)
404 Ressource non trouvée
422 Erreur de validation Pydantic
500 Erreur serveur interne

Authentification

Toutes les routes protégées nécessitent le header :

Authorization: Bearer <access_token>