From cd0039503910e14681687ae2b7960c378d4e1138 Mon Sep 17 00:00:00 2001 From: Erwann PHILIPPE Date: Wed, 16 Sep 2026 14:42:38 +0200 Subject: [PATCH] Ajout du README --- README.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d96f822 --- /dev/null +++ b/README.md @@ -0,0 +1,131 @@ +# 🚗 API REST Voitures + +API REST en **PHP 8 / MySQL** pour la gestion d'un parc automobile (voitures, plaques d'immatriculation, relevés kilométriques, entretiens, notes de suivi) avec système d'authentification par jeton et contrôle des droits par propriétaire et administrateur. + +--- + +## ⚙️ Configuration & Prérequis + +- **Environnement** : WampServer (Apache + MySQL + PHP 8.x) +- **Base de données** : `voituresapi` + - Gérable via **phpMyAdmin** : `http://localhost/phpmyadmin5.2.3/index.php` + - Fichier de structure & données : [`voituresapi (1).sql`](./voituresapi%20(1).sql) +- **Fichier de connexion** : [`config.php`](./config.php) + - Hôte : `127.0.0.1:3306` | Utilisateur : `root` | Mot de passe : `""` (vide) + +--- + +## 🔐 Authentification & Rôles + +Les requêtes protégées requièrent l'en-tête HTTP : +```http +Authorization: Bearer +``` +*(ou `X-API-KEY: `, ou le paramètre `?token=`)* + +### Comptes de démonstration préconfigurés : +| Rôle | Utilisateur | Mot de passe | Jeton direct (`api_token`) | Droits | +|---|---|---|---|---| +| **Admin** | `admin` | `adminpassword` | `admin-token-secret-12345` | **Accès total** : consultation, modification et suppression de tout véhicule et contenu | +| **Utilisateur** | `user` | `userpassword` | `user-token-secret-67890` | **Propriétaire** : gestion de ses propres véhicules, kilométrages, entretiens et notes | + +--- + +## 📡 Endpoints de l'API + +### 1. Authentification (`/auth`) +| Méthode | Endpoint | Accès | Description | +|---|---|---|---| +| `POST` | `/auth/login` | **Public** | Connexion (`username`, `password`) et récupération d'un jeton | +| `POST` | `/auth/register` | **Public** | Inscription d'un nouvel utilisateur (`username`, `password`, `nom`) | +| `GET` | `/auth/me` | **Authentifié** | Obtenir le profil et rôle du compte connecté | +| `POST` | `/auth/logout` | **Authentifié** | Révocation du jeton de session | + +--- + +### 2. Voitures (`/cars`) +| Méthode | Endpoint | Accès | Description | +|---|---|---|---| +| `GET` | `/cars` | **Public** | Liste toutes les voitures *(filtrable par `?immatriculation=...`, `?user_id=...`, `?mine=true`)* | +| `GET` | `/cars/mes-voitures` | **Authentifié** | Liste uniquement les voitures appartenant à l'utilisateur connecté | +| `GET` | `/cars/{id}` | **Public** | Fiche d'une voiture avec son dernier km et son propriétaire | +| `GET` | `/cars/immatriculation/{plaque}` | **Public** | Identification par plaque *(insensible à la casse, espaces et tirets, ex: `AB-123-CD`)* | +| `GET` | `/cars/{id}/etat` | **Propriétaire ou Admin** | État complet *(voiture, dernier km, historique entretiens et notes de suivi)* | +| `POST` | `/cars` | **Authentifié** | Créer une voiture *(attribuée automatiquement à l'utilisateur connecté)* | +| `PUT` | `/cars/{id}` | **Propriétaire ou Admin** | Mettre à jour les paramètres d'une voiture *(marque, modèle, année, immatriculation...)* | +| `DELETE` | `/cars/{id}` | **Propriétaire ou Admin** | Supprimer une voiture et toutes ses données associées *(cascade)* | + +#### Corps attendu pour `POST /cars` : +```json +{ + "marque": "Renault", + "modele": "Clio V", + "annee": 2021, + "dateAchat": "2023-06-15", + "immatriculation": "AB-123-CD", + "VIN": "VF1RJA00012345678", + "kilometrage_initial": 45000 +} +``` + +--- + +### 3. Kilométrage (`/cars/{id}/kilometrage` & `/kilometrage`) +| Méthode | Endpoint | Accès | Description | +|---|---|---|---| +| `GET` | `/cars/{id}/kilometrage` | **Public** | Historique des relevés kilométriques d'une voiture | +| `POST` | `/cars/{id}/kilometrage` | **Propriétaire ou Admin** | Ajouter un relevé (`valeur`, `date_releve` optionnelle) | +| `DELETE` | `/kilometrage/{id}` | **Propriétaire ou Admin** | Supprimer un relevé kilométrique | + +--- + +### 4. Entretiens / Maintenance (`/cars/{id}/maintenance` & `/maintenance`) +| Méthode | Endpoint | Accès | Description | +|---|---|---|---| +| `GET` | `/cars/{id}/maintenance` | **Public** | Historique des entretiens d'une voiture | +| `GET` | `/maintenance/{id}` | **Public** | Détail d'un entretien spécifique | +| `POST` | `/cars/{id}/maintenance` | **Propriétaire ou Admin** | Enregistrer un entretien (`type_entretien`, `date_evenement`, `kilometrage`, `description`, `prix`) | +| `PUT` | `/maintenance/{id}` | **Propriétaire ou Admin** | Modifier un entretien | +| `DELETE` | `/maintenance/{id}` | **Propriétaire ou Admin** | Supprimer un entretien | + +--- + +### 5. Notes de suivi confidentielles (`/cars/{id}/notes` & `/notes`) +| Méthode | Endpoint | Accès | Description | +|---|---|---|---| +| `GET` | `/cars/{id}/notes` | **Propriétaire ou Admin** | Consulter les notes de suivi interne d'une voiture | +| `POST` | `/cars/{id}/notes` | **Propriétaire ou Admin** | Ajouter une note (`titre`, `contenu`) | +| `PUT` | `/notes/{id}` | **Propriétaire ou Admin** | Modifier une note | +| `DELETE` | `/notes/{id}` | **Propriétaire ou Admin** | Supprimer une note | + +--- + +## 🧪 Exemples rapides de requêtes (cURL) + +#### 1. Identification par plaque (Public) : +```bash +curl -X GET "http://localhost/voitureAPI/cars/immatriculation/AB-123-CD" +``` + +#### 2. Connexion : +```bash +curl -X POST "http://localhost/voitureAPI/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"username": "user", "password": "userpassword"}' +``` + +#### 3. Création d'une voiture (Authentifié) : +```bash +curl -X POST "http://localhost/voitureAPI/cars" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer user-token-secret-67890" \ + -d '{"marque": "Peugeot", "modele": "308", "annee": 2022, "dateAchat": "2023-01-10", "immatriculation": "GA-987-ZB"}' +``` + +#### 4. Modification de sa voiture (Propriétaire ou Admin) : +```bash +curl -X PUT "http://localhost/voitureAPI/cars/2" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer user-token-secret-67890" \ + -d '{"modele": "208 GT Line"}' +```