Ajout du dossier api avec la géolocalisation automatique des casernes de pompiers
This commit is contained in:
d6soft
300
api/docs/TECHBOOK.md
Normal file
300
api/docs/TECHBOOK.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Documentation Technique API RESTful PHP 8.3
|
||||
|
||||
## Table des matières
|
||||
|
||||
1. [Structure du projet](#structure-du-projet)
|
||||
2. [Configuration du serveur](#configuration-du-serveur)
|
||||
3. [Flux d'une requête](#flux-dune-requête)
|
||||
4. [Architecture des composants](#architecture-des-composants)
|
||||
5. [Base de données](#base-de-données)
|
||||
6. [Sécurité](#sécurité)
|
||||
7. [Endpoints API](#endpoints-api)
|
||||
|
||||
## Structure du projet
|
||||
|
||||
```plaintext
|
||||
/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
|
||||
|
||||
```http
|
||||
POST /api/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePassword123"
|
||||
}
|
||||
```
|
||||
|
||||
**Réponse réussie :**
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```http
|
||||
POST /api/logout
|
||||
```
|
||||
|
||||
**Réponse réussie :**
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```http
|
||||
POST /api/users
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com",
|
||||
"password": "SecurePassword123"
|
||||
}
|
||||
```
|
||||
|
||||
**Réponse réussie :**
|
||||
|
||||
```json
|
||||
{
|
||||
"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 :
|
||||
|
||||
```javascript
|
||||
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
|
||||
Reference in New Issue
Block a user