# Documentation Complète et Détaillée de l'API - Architecture et Endpoints

*   **Version :** 1.3
*   **Date :** 1er novembre 2025
*   **Auteur :** Yoann

## 1. Principes d'Architecture

### 1.1. Préfixe d'URL Personnalisé
Pour des raisons de sécurité, toutes les routes de l'API utiliseront le préfixe `/access-point`. L'objectif est de ne pas exposer un point d'entrée générique et facilement ciblable par des scans automatisés.

**URL de base de l'API :** `https://famille.labiau.fr/access-point`

### 1.2. Codes de Réponse et Erreurs
*   **Authentification :** Une route nécessitant une authentification renverra `401 Unauthorized` si l'utilisateur n'est pas connecté.
*   **Autorisation :** Une route d'administration renverra `403 Forbidden` si un utilisateur connecté mais non-administrateur tente d'y accéder.
*   **Validation :** Les données invalides dans une requête (ex: email mal formé) provoqueront une erreur `400 Bad Request` ou `422 Unprocessable Entity`, souvent accompagnée d'un message détaillant les champs en erreur.

---

## 2. Route de Test de Disponibilité (Health Check)

### **GET /health**
*   **Description :** Route publique pour vérifier que le service API est en ligne.
*   **Accès :** Public (aucune authentification requise).
*   **Réponse (`200 OK`) :**
    ```
    {
      "status": "available",
      "timestamp": "2025-11-01T09:30:00Z"
    }
    ```

---

## 3. Endpoints d'Authentification

### **POST /register**
*   **Description :** Crée un nouvel utilisateur.
*   **Corps de la requête :**
    ```
    { 
        "username": "...", 
        "email": "...", 
        "password": "..." 
    }
    ```
*   **Réponses :**
    *   `201 Created` : Succès.
    *   `400 Bad Request` : Données invalides (mot de passe trop faible, etc.).
    *   `409 Conflict` : Le `username` ou l'`email` existe déjà.

### **GET /verify-email**
*   **Description :** Active un compte via le `token` reçu par email.
*   **Paramètre d'URL :** `?token={token}`
*   **Réponses :**
    *   `200 OK` : Compte activé avec succès.
    *   `400 Bad Request` : Token invalide ou expiré.

### **POST /login**
*   **Description :** Authentifie un utilisateur.
*   **Corps de la requête :**
    ```
    { 
        "username": "...", 
        "password": "..." 
    }
    ```
*   **Réponses :**
    *   `200 OK` : Succès (si le 2FA est désactivé). La session est créée.
    *   `202 Accepted` : Identifiants corrects, mais une validation 2FA est requise.
    *   `401 Unauthorized` : Identifiants incorrects ou compte inactif.

### **POST /login/2fa**
*   **Description :** Valide le code 2FA (TOTP) après une première étape de connexion.
*   **Corps de la requête :**
    ```
    { 
        "code": "123456" 
    }
    ```
*   **Réponses :**
    *   `200 OK` : Code valide. La session est maintenant pleinement authentifiée.
    *   `401 Unauthorized` : Code invalide.

### **POST /logout**
*   **Description :** Met fin à la session de l'utilisateur.
*   **Accès :** Authentifié.
*   **Réponses :**
    *   `200 OK` : Déconnexion réussie.
    *   `401 Unauthorized` : Pas connecté.

### **POST /password/forgot**
*   **Description :** Déclenche l'envoi d'un email de réinitialisation.
*   **Corps de la requête :**
    ```
    { 
        "email": "..." 
    }
    ```
*   **Réponse (`200 OK`) :** Renvoie toujours un succès pour ne pas révéler si une adresse email existe dans le système.

### **POST /password/reset**
*   **Description :** Met à jour le mot de passe avec un token.
*   **Corps de la requête :**
    ```
    { 
        "token": "...", 
        "new_password": "..." 
    }
    ```
*   **Réponses :**
    *   `200 OK` : Mot de passe mis à jour.
    *   `400 Bad Request` : Token invalide/expiré ou mot de passe trop faible.

---

## 4. Endpoints Utilisateur (Connecté)

### **GET /applications**
*   **Description :** Renvoie la liste des applications accessibles par l'utilisateur connecté.
*   **Accès :** Authentifié.
*   **Réponse (`200 OK`) :** Un tableau d'objets `application`.
    ```
    [
        { 
            "id": 1, 
            "name": "...", 
            "description": "...", 
            "url": "...", 
            "icon": "..." 
        }
    ]
    ```
*   **Erreur :** `401 Unauthorized`.

---

## 5. Endpoints d'Administration (Rôle `admin` requis)

### **GET /admin/users**
*   **Description :** Récupère la liste de tous les utilisateurs et leurs rôles.
*   **Réponse (`200 OK`) :** Un tableau d'objets `utilisateur` avec leurs rôles imbriqués.
    ```
    [
        {
            "id": 1, 
            "username": "...", 
            "email": "...", 
            "roles": [
                { 
                    "id": 1, 
                    "name": "admin" 
                }
            ] 
        }
    ]
    ```
*   **Erreurs :** `401 Unauthorized`, `403 Forbidden`.

### **GET /admin/roles**
*   **Description :** Récupère la liste de tous les rôles configurables dans le système.
*   **Réponse (`200 OK`) :** Un tableau d'objets `rôle`.
    ```
    [
        { 
            "id": 1, 
            "name": "admin", 
            "description": "..." 
        }
    ]
    ```
*   **Erreurs :** `401 Unauthorized`, `403 Forbidden`.

### **PUT /admin/users/{id}/roles**
*   **Description :** Remplace l'ensemble des rôles pour un utilisateur spécifique.
*   **Paramètre d'URL :** `{id}` de l'utilisateur.
*   **Corps de la requête :** Un objet contenant un tableau d'IDs de rôles.
    ```
    { 
        "roles":  
    }
    ```
*   **Réponse (`200 OK`) :** Renvoie l'objet utilisateur mis à jour.
    ```
    { 
        "id": 2, 
        "username": "...", 
        "roles": [
            { 
                "id": 2, 
                "name": "..." 
            }, 
            { 
                "id": 4, 
                "name": "..." 
            }
        ] 
    }
    ```
*   **Erreurs :**
    *   `400 Bad Request` / `422 Unprocessable Entity` : Données invalides (ex: ID de rôle inexistant).
    *   `401 Unauthorized` : Non connecté.
    *   `403 Forbidden` : Pas le rôle `admin`.
    *   `404 Not Found` : L'utilisateur `{id}` n'existe pas.