geo/api/docs/TECHBOOK.md

Documentation Technique API RESTful PHP 8.3

Table des matières

1. Structure du projet
2. Configuration du serveur
3. Flux d'une requête
4. Architecture des composants
5. Base de données
6. Sécurité
7. Endpoints API

Structure du projet

/api/
├── docs/
│   └── TECHBOOK.md
├── src/
│   ├── Controllers/
│   │   └── UserController.php
│   ├── Core/
│   │   ├── Router.php
│   │   ├── Request.php
│   │   ├── Response.php
│   │   ├── Session.php
│   │   └── Database.php
│   └── Config/
│       └── config.php
├── index.php
└── .htaccess

Configuration du serveur

Prérequis

• Debian 12
• NGINX
• PHP 8.3-FPM
• MariaDB 10.11

Configuration NGINX

Le serveur NGINX est configuré pour rediriger toutes les requêtes vers le point d'entrée index.php de l'API.

Configuration PHP-FPM

PHP-FPM est configuré pour gérer les processus PHP avec des paramètres optimisés pour une API.

Flux d'une requête

Exemple détaillé du parcours d'une requête POST /api/users :

1. Entrée de la requête

   • La requête arrive sur le serveur NGINX
   • NGINX redirige vers PHP-FPM via le socket unix
   • Le fichier .htaccess redirige vers index.php

2. Initialisation (index.php)

   • Chargement des dépendances
   • Initialisation de la configuration
   • Démarrage de la session
   • Configuration des headers CORS
   • Initialisation du routeur

3. Routage

   • Le Router analyse la méthode HTTP (POST)
   • Analyse de l'URI (/api/users)
   • Correspondance avec les routes enregistrées
   • Instanciation du Controller approprié

4. Traitement (UserController)

   • Vérification de l'authentification
   • Récupération des données JSON
   • Validation des données reçues
   • Traitement métier
   • Interaction avec la base de données
   • Préparation de la réponse

5. Réponse

   • Formatage de la réponse en JSON
   • Configuration des headers de réponse
   • Envoi au client

Architecture des composants

Core Components

Router

• Gère le routage des requêtes
• Associe les URLs aux Controllers
• Gère les paramètres d'URL
• Dispatch vers les méthodes appropriées

Request

• Parse les données entrantes
• Gère les différents types de contenu
• Nettoie et valide les entrées
• Fournit une interface unifiée pour accéder aux données

Response

• Formate les réponses en JSON
• Gère les codes HTTP
• Configure les headers de réponse
• Assure la cohérence des réponses

Session

• Gère l'état des sessions
• Stocke les données d'authentification
• Vérifie les permissions
• Sécurise les données de session

Database

• Gère la connexion à MariaDB
• Fournit une interface PDO
• Gère le pool de connexions
• Assure la sécurité des requêtes

Sécurité

Mesures implémentées

• Validation stricte des entrées
• Protection contre les injections SQL (PDO)
• Hachage sécurisé des mots de passe
• Headers de sécurité HTTP
• Gestion des CORS
• Session sécurisée
• Authentification requise

Endpoints API

Routes Publiques vs Privées

L'API distingue deux types de routes :

Routes Publiques

• POST /api/login
• POST /api/register
• GET /api/health

Routes Privées (Nécessitent une session authentifiée)

• Toutes les autres routes

Authentification

L'authentification utilise le système de session PHP natif.

Login

POST /api/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "SecurePassword123"
}

Réponse réussie :

{
  "message": "Connecté avec succès",
  "user": {
    "id": 123,
    "email": "user@example.com"
  }
}

Notes importantes :

• Un cookie de session PHP sécurisé est automatiquement créé
• Le cookie est httpOnly, secure et SameSite=Strict
• L'ID de session est régénéré à chaque login réussi

Logout

POST /api/logout

Réponse réussie :

{
  "message": "Déconnecté avec succès"
}

Sécurité des Sessions

La configuration des sessions inclut :

• Sessions PHP natives sécurisées

• Protection contre la fixation de session

• Cookies httpOnly (protection XSS)

• Mode strict pour les cookies

• Validation côté serveur à chaque requête

• use_strict_mode = 1

• cookie_httponly = 1

• cookie_secure = 1

• cookie_samesite = Strict

• Régénération de l'ID de session après login

• Destruction complète de la session au logout

Users

Création d'utilisateur

POST /api/users
Content-Type: application/json

{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "SecurePassword123"
}

Réponse réussie :

{
  "message": "Utilisateur créé",
  "id": "123"
}

Codes de statut :

• 201: Création réussie
• 400: Données invalides
• 401: Non authentifié
• 500: Erreur serveur

Autres endpoints

• GET /api/users
• GET /api/users/{id}
• PUT /api/users/{id}
• DELETE /api/users/{id}

Intégration Frontend

Configuration des Requêtes

Toutes les requêtes API depuis le frontend doivent inclure :

fetch('/api/endpoint', {
  credentials: 'include', // Important pour les cookies de session
  // ... autres options
});

Gestion des Sessions

• Les cookies de session sont automatiquement gérés par le navigateur
• Pas besoin de stocker ou gérer des tokens manuellement
• Redirection vers /login si session expirée (401)

Maintenance et Déploiement

Logs

• Logs d'accès NGINX : /var/log/nginx/api-access.log
• Logs d'erreur NGINX : /var/log/nginx/api-error.log
• Logs PHP : /var/log/php/php-error.log

Déploiement

1. Pull du repository
2. Vérification des permissions
3. Configuration de l'environnement
4. Tests des endpoints
5. Redémarrage des services

Surveillance

• Monitoring des processus PHP-FPM
• Surveillance de la base de données
• Monitoring des performances
• Alertes sur erreurs critiques