138 lines
6.1 KiB
Markdown
138 lines
6.1 KiB
Markdown
# 🚗 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 <token>
|
|
```
|
|
*(ou `X-API-KEY: <token>`, ou le paramètre `?token=<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 de l'ensemble du parc (/cars, immatriculation), modification et suppression de tout véhicule et contenu |
|
|
| **Utilisateur** | `user` | `userpassword` | `user-token-secret-67890` | **Propriétaire** : gestion de ses propres véhicules (/cars/mes-voitures), 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` | **Admin** | 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}` | **Admin** | 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 (Admin requis) :
|
|
```bash
|
|
curl -X GET "http://localhost/voitureAPI/cars/immatriculation/AB-123-CD" \
|
|
-H "Authorization: Bearer admin-token-secret-12345"
|
|
```
|
|
|
|
#### 2. Liste de toutes les voitures (Admin requis) :
|
|
```bash
|
|
curl -X GET "http://localhost/voitureAPI/cars" \
|
|
-H "Authorization: Bearer admin-token-secret-12345"
|
|
```
|
|
|
|
#### 3. 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"}'
|
|
```
|