Documentation API Complète - Librairie BookStore

📚 Documentation API Complète

API RESTful pour la gestion d'une librairie en ligne avec système complet d'authentification, gestion des auteurs, publication de livres, commandes, avis, certification et administration.

52 Endpoints API
4 Rôles Utilisateur
13 Tables Base de Données
7 Contrôleurs
🔐

Authentification Sécurisée

Tokens JWT, protection CSRF, sessions sécurisées, validation des entrées et hachage des mots de passe

📚

Catalogue Intelligent

Recherche full-text, filtrage multi-critères, pagination, statistiques de consultation

✍️

Espace Auteur Complet

Publication, gestion des livres, coupons de réduction, certification d'identité

🛒

Système de Commandes

Panier, checkout, application de coupons, suivi des achats en temps réel

⭐

Avis & Interactions

Notation 5 étoiles, commentaires, système de likes/dislikes avec gestion des votes

🛡️

Administration Puissante

Gestion utilisateurs, certification auteurs, configuration site, supervision complète

🎯 Rôles et Permissions

Rôle Middlewares Préfixe API Description
Public Aucun /api/* Visiteur non connecté - Accès au catalogue, profils publics
Utilisateur auth /api/user/* Compte connecté standard - Commandes, avis, profil
Auteur auth + author /api/author/* Utilisateur avec is_author = true
Admin auth + admin /api/admin/* Super-utilisateur is_admin = true
💡 Note importante : Les administrateurs (is_admin = true) ont implicitement tous les droits, y compris les droits d'auteur. Un utilisateur peut être auteur sans être admin. La certification (is_verified_author) est distincte du statut d'auteur.

📋 Table des Matières des Endpoints

🔓 Authentification

Routes publiques ne nécessitant pas d'authentification préalable.

Méthode Endpoint Description Protection
POST /api/login Connexion utilisateur - Retourne token JWT et CSRF Aucune
POST /api/register Inscription nouvel utilisateur - Retourne token JWT et CSRF Aucune

Exemple Connexion

// Requête POST /api/login Content-Type: application/json { "email": "john@example.com", "password": "secret123" } // Réponse 200 { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "John Doe", "email": "john@example.com", "is_admin": false, "is_active": true, "session_token": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": "2024-12-31 23:59:59", "csrf_token": "a1b2c3d4e5f6..." } }

Exemple Inscription

// Requête POST /api/register Content-Type: application/json { "name": "Jane Doe", "email": "jane@example.com", "password": "securepass123" } // Réponse 201 { "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Jane Doe", "email": "jane@example.com", "is_admin": false, "is_active": true, "session_token": { "token": "eyJhbGciOiJIUzI1NiIs...", "expires_at": "2024-12-31 23:59:59", "csrf_token": "f6e5d4c3b2a1..." } }

📚 Catalogue de Livres

Consultation publique du catalogue avec recherche et filtrage.

Méthode Endpoint Description Paramètres
GET /api/books Liste et filtre le catalogue ?search=&category_id=&author_id=&page=1&per_page=12
GET /api/books/{id} Détails d'un livre + enregistrement vue {id} : UUID du livre

Exemple Recherche

// Requête GET /api/books?search=php&category_id=cat123&page=1&per_page=12 // Réponse 200 { "books": [ { "id": "book-uuid", "title": "PHP pour les débutants", "author_name": "John Doe", "description": "Un guide complet...", "cover_image": "/uploads/covers/php-book.jpg", "price": 29.99, "is_published": true } ], "page": 1, "per_page": 12 }

Exemple Détails Livre

// Requête GET /api/books/book-uuid // Réponse 200 { "id": "book-uuid", "title": "PHP pour les débutants", "author_name": "John Doe", "author_id": "author-uuid", "description": "Un guide complet pour apprendre PHP...", "cover_image": "/uploads/covers/php-book.jpg", "file_url": "/uploads/books/php-book.pdf", "price": 29.99, "categories": [ { "id": "cat123", "name": "Programmation", "slug": "programmation" } ], "average_rating": 4.5 }

🏷️ Catégories

Méthode Endpoint Description
GET /api/categories Liste toutes les catégories disponibles
// Réponse 200 [ { "id": "cat1", "name": "Programmation", "slug": "programmation" }, { "id": "cat2", "name": "Science-Fiction", "slug": "science-fiction" }, { "id": "cat3", "name": "Histoire", "slug": "histoire" } ]

⭐ Avis (Consultation Publique)

Méthode Endpoint Description
GET /api/reviews/book/{book_id} Avis pour un livre spécifique
// Requête GET /api/reviews/book/book-uuid // Réponse 200 [ { "id": "review-1", "book_id": "book-uuid", "user_id": "user-uuid", "rating": 5, "comment": "Excellent livre !", "likes_count": 12, "dislikes_count": 1, "user_vote": null } ]

👤 Profils Auteurs (Public)

Méthode Endpoint Description
GET /api/authors/{user_id} Profil public d'un auteur avec ses livres
// Réponse 200 { "author": { "name": "John Doe", "bio": "Développeur passionné...", "avatar": "/uploads/avatars/john.jpg", "banner": "/uploads/banners/john-banner.jpg", "website": "https://johndoe.com", "is_verified": true }, "books": [...] }

🎫 Validation de Coupons (Public)

Méthode Endpoint Description
GET /api/coupons/validate Valide un code coupon avant achat
// Requête GET /api/coupons/validate?code=PROMO2024 // Réponse 200 { "code": "PROMO2024", "discount_type": "percentage", "discount_value": 20 } // Erreur 410 (expiré) { "message": "Coupon expiré ou épuisé" }

⚙️ Paramètres Publics

Méthode Endpoint Description
GET /api/settings/public Paramètres publics du site
// Réponse 200 { "site_name": "Ma Librairie En Ligne", "allowed_file_types": "pdf,epub,mobi", "author_commission_percentage": "70" }

👤 Profil Utilisateur Auth Requise

Gestion du profil personnel de l'utilisateur connecté.

Méthode Endpoint Description Protection
GET /api/user Profil complet avec livres et commandes auth
GET /api/user/profile Profil simplifié (id, name, email, rôles) auth
POST /api/user/update Mise à jour nom et email auth csrf
POST /api/user/password Changement de mot de passe auth csrf
POST /api/logout Déconnexion et invalidation du token auth
GET /api/session/check Vérification validité session auth

Exemple Profil Complet

// Requête GET /api/user Authorization: Bearer eyJhbGciOi... // Réponse 200 { "user": { "id": "user-uuid", "name": "John Doe", "email": "john@example.com", "is_author": true, "is_admin": false, "is_active": true }, "author_profile": {...}, "books": [...], "orders": [...], "books_count": 3, "orders_count": 5 }

Exemple Changement Mot de Passe

// Requête POST /api/user/password Authorization: Bearer eyJhbGciOi... X-CSRF-Token: a1b2c3d4... Content-Type: application/x-www-form-urlencoded current_password=oldpass123&new_password=newpass456&confirm_password=newpass456 // Réponse 200 { "message": "Mot de passe changé avec succès" }

⭐ Avis (Actions) Auth Requise

Méthode Endpoint Description Protection
POST /api/reviews Créer un avis (1 à 5 étoiles) auth csrf
POST /api/reviews/vote Voter like/dislike sur un avis auth csrf

Exemple Vote (Toggle)

// Requête POST /api/reviews/vote Content-Type: application/json { "review_id": "review-123", "vote_type": "like" } // Réponses possibles { "action": "added" } // Nouveau like ajouté { "action": "removed" } // Like retiré (2ème clic) { "action": "changed" } // Changement like↔dislike

🛒 Commandes Auth Requise

Méthode Endpoint Description Protection
GET /api/orders Liste toutes les commandes de l'utilisateur auth
GET /api/orders/{id} Détails d'une commande (items + coupons) auth
POST /api/orders/checkout Créer une commande (checkout) auth csrf

Exemple Checkout

// Requête POST /api/orders/checkout Authorization: Bearer eyJhbGciOi... X-CSRF-Token: a1b2c3d4... Content-Type: application/json { "book_ids": ["book-uuid-1", "book-uuid-2"], "coupon_code": "PROMO2024" } // Réponse 201 { "order_id": "order-uuid", "total": 23.99 }

✍️ Profil Auteur Auteur Requis

Méthode Endpoint Description Protection
POST /api/author/profile Créer ou mettre à jour le profil auteur auth author
// Requête POST /api/author/profile Content-Type: application/json { "bio": "Auteur passionné de science-fiction...", "avatar": "/uploads/avatars/author.jpg", "banner": "/uploads/banners/author-banner.jpg", "website": "https://mon-site.com" }

✅ Certification Auteur Auth Requise

Méthode Endpoint Description Protection
POST /api/author/verification/request Soumettre une demande de certification auth csrf
// Requête POST /api/author/verification/request Content-Type: application/json { "id_card_url": "/uploads/verifications/id-card.jpg", "id_face_url": "/uploads/verifications/selfie.jpg" } // Réponse 200 { "message": "Demande de vérification soumise avec succès" } // Erreur 409 (déjà en cours) { "message": "Une demande de vérification est déjà en cours de traitement" }

📚 Gestion des Livres Auteur Requis

Méthode Endpoint Description Protection
POST /api/author/books Publier un nouveau livre auth author csrf
PUT /api/author/books/{id} Modifier un de ses livres auth author csrf
DELETE /api/author/books/{id} Supprimer un de ses livres auth author csrf
// Création d'un livre POST /api/author/books Content-Type: application/json { "title": "Mon Nouveau Roman", "description": "Une histoire captivante...", "cover_image": "/uploads/covers/roman.jpg", "file_url": "/uploads/books/roman.pdf", "price": 14.99, "category_ids": ["cat1", "cat2"] } // Réponse 201 { "id": "new-book-uuid" }

🎫 Gestion des Coupons Auteur Requis

Méthode Endpoint Description Protection
GET /api/author/coupons Liste ses coupons auth author
POST /api/author/coupons Créer un nouveau coupon auth author csrf
DELETE /api/author/coupons/{id} Supprimer un de ses coupons auth author csrf
// Création d'un coupon POST /api/author/coupons Content-Type: application/json { "code": "LANCEMENT2024", "discount_type": "percentage", "discount_value": 25, "expires_at": "2024-12-31 23:59:59", "max_uses": 100 } // Réponse 201 { "id": "coupon-uuid" }

🛡️ Administration - Utilisateurs Admin Requis

Méthode Endpoint Description Protection
GET /api/admin/users Liste tous les utilisateurs auth admin
GET /api/admin/users/{id} Détails complets d'un utilisateur auth admin
POST /api/admin/users/{id}/toggle Activer/Désactiver un compte auth admin csrf

🛡️ Administration - Livres Admin Requis

Méthode Endpoint Description Protection
PUT /api/admin/books/{id} Modifier n'importe quel livre auth admin csrf
DELETE /api/admin/books/{id} Supprimer n'importe quel livre auth admin csrf

🛡️ Administration - Catégories Admin Requis

Méthode Endpoint Description Protection
POST /api/admin/categories Créer une nouvelle catégorie auth admin csrf
// Requête POST /api/admin/categories Content-Type: application/json { "name": "Développement Personnel", "slug": "developpement-personnel" } // Réponse 201 { "id": "new-cat-uuid" }

🛡️ Administration - Commandes Admin Requis

Méthode Endpoint Description Protection
PUT /api/admin/orders/{id}/status Changer le statut d'une commande auth admin csrf
// Requête PUT /api/admin/orders/order-uuid/status Content-Type: application/json { "status": "completed" } // Statuts possibles : "pending", "completed", "failed"

🛡️ Administration - Certification Admin Requis

Méthode Endpoint Description Protection
GET /api/admin/verifications Liste les demandes de certification auth admin
POST /api/admin/verifications/process Approuver ou rejeter une certification auth admin csrf
// Approuver une certification POST /api/admin/verifications/process Content-Type: application/json { "id": "verification-uuid", "status": "approved" } // Rejeter une certification { "id": "verification-uuid", "status": "rejected", "rejection_reason": "Pièce d'identité illisible" }

🛡️ Administration - Paramètres Admin Requis

Méthode Endpoint Description Protection
POST /api/admin/settings Mettre à jour un paramètre du site auth admin csrf
// Requête POST /api/admin/settings Content-Type: application/json { "key": "site_name", "value": "Ma Nouvelle Librairie" } // Réponse 200 { "key": "site_name", "value": "Ma Nouvelle Librairie" }

🛡️ Administration - Coupons Admin Requis

Méthode Endpoint Description Protection
DELETE /api/admin/coupons/{id} Supprimer n'importe quel coupon auth admin csrf

📊 Résumé des Contrôleurs et Modèles

Contrôleur Modèles Utilisés Nombre de Routes
UserController User 8 routes (2 publiques + 6 auth)
BookController Book, Category, BookCategory, BookView, Review, User 6 routes (3 publiques + 3 auteur)
AuthorController Author, User, AuthorVerification 5 routes (1 publique + 2 auteur + 2 admin)
ReviewController Review, ReviewVote 3 routes (1 publique + 2 auth)
OrderController Order, OrderItem, OrderCoupon, Book, Coupon 4 routes (3 auth + 1 admin)
CouponController Coupon, User 5 routes (1 publique + 3 auteur + 1 admin)
SettingController Setting 2 routes (1 publique + 1 admin)

📚 BookStore API Documentation v1.0.0

GitHub  |  Support  |  Contact

🔐 Authentification JWT  |  🛡️ Protection CSRF  |  🔒 Sessions Sécurisées  |  📝 Validation des Entrées