API PLATFORM
API Platform — REST API Bibliothèque
PHP 8.2+
Symfony 5.4
API Platform
MySQL 8.0
JSON
API Platform est une RESTful API complète pour la gestion d'une bibliothèque. Le projet démontre une maîtrise des concepts API modernes : entities Doctrine auto-exposées, filtres sophistiqués, validations robustes, et documentation Swagger/OpenAPI automatique.
📊 Stack Technique
- Framework : Symfony 5.4 + API Platform Core
- ORM : Doctrine (relations ManyToOne, OneToMany, ManyToMany)
- Sérialisation : Normalizers/Denormalizers JSON (HATEOAS links)
- Validation : Symfony Validator (Assert, UniqueEntity)
- Filtrage : SearchFilter, RangeFilter, OrderFilter, PropertyFilter
- Documentation : Swagger UI / OpenAPI auto-généré
- Pagination : Gestion automatique par API Platform
🗂️ Modèle de données (7 entités)
- Livre : ISBN, titre, prix, année, langue, genre, éditeur, auteur. Filters: SearchFilter (titre ipartial, auteur exact), RangeFilter (prix), OrderFilter, PropertyFilter
- Auteur : Nom, prénom, nationalité. ManyToMany inversed via Livre. SearchFilter (nom/prénom partial)
- Genre : Libellé unique. OneToMany vers Livre. SearchFilter (libellé partial)
- Éditeur : Nom unique. OneToMany vers Livre. Tri par défaut (nom ASC)
- Nationalité : Libellé unique. OneToMany vers Auteur. Validations UniqueEntity, Length
- Adhérent : Profil utilisateur (nom, prénom, adresse, mail unique, tel, password). Implémente UserInterface. Rôles (ROLE_ADMIN, ROLE_MANAGER, ROLE_ADHERENT)
- Prêt : Dates (datePret, dateRetourPrevu, dateRetourReel). ManyToOne vers Livre et Adhérent
🔌 Fonctionnalités API (CRUD automatique)
- GET /api/livres : Liste paginée, sortable, filtrable, avec sélection de properties
- POST /api/livres : Créer un livre (validations ISBN-10, prix, longueur titre)
- GET /api/livres/{id} : Détail complet avec relations (auteur, genre, éditeur)
- PUT/PATCH /api/livres/{id} : Mise à jour partielle ou complète
- DELETE /api/livres/{id} : Suppression
- GET /api/auteurs, /api/genres, /api/editeurs, /api/adherents, /api/prets : Endpoints CRUD pour chaque ressource
🔍 Filtres sophistiqués
- SearchFilter : Recherche textuelle (titre ipartial, auteur exact) sur Livre/Auteur/Genre
- RangeFilter : Filtrage numérique (ex: prix entre 10 et 50 €)
- OrderFilter : Tri multi-colonnes (titre ASC, prix DESC, auteur.nom ASC)
- PropertyFilter : Sélection dynamique des champs retournés (whitelist: isbn, titre, prix, etc.)
- Exemple : GET /api/livres?titre=harry&prix[gte]=15&prix[lte]=30&order[titre]=ASC&properties[]=isbn&properties[]=titre
✅ Validations robustes
- Livre : ISBN-10 obligatoire et valide, titre unique (2-100 chars), prix positif (5-400€)
- Auteur : Nom/prénom, nationalité obligatoire (ManyToOne)
- Genre : Libellé unique et non-vide (UniqueEntity + NotBlank)
- Éditeur : Nom unique (4-50 chars)
- Nationalité : Libellé unique et validé (4-50 chars)
- Adhérent : Mail unique (UserInterface), roles array, mot de passe
- Prêts : Relations obligatoires (livre, adhérent), dates validées
💡 Points clés d'implémentation
- #[ApiResource()] : Décorateur qui expose automatiquement l'entité en CRUD REST
- Attributs Doctrine : Toutes les relations (ManyToOne, OneToMany, ManyToMany) configurées
- Décorateurs API Platform : #[ApiFilter()], #[ApiSubresource()], attributs personnalisés sur chaque entité
- Validators : @Assert annotations (ISBN, Range, Length, Positive, UniqueEntity)
- HATEOAS : Links automatiques entre ressources (ex: livre → auteur, genre, éditeur)
- Pagination : Configurable via query params (itemsPerPage, page)
- JSON-LD : Contexte semantique, types complets dans réponse
📚 Cas d'usage réels
- Frontend SPA/Mobile : Consomme l'API via fetch/axios, affiche livres/auteurs filtrés
- Système de prêt : Créer prêt (POST /api/prets), tracker dateRetourReel
- Catalogue : Recherche = GET /api/livres?titre=...&genre=... retourne liste + metadata
- Gestion adhérents : CRUD utilisateurs avec rôles (ROLE_ADMIN peut tout, ROLE_ADHERENT limité)
- Intégration tiers : API documentée (Swagger) → facile à intégrer pour partenaires
🎯 Compétences démontrées
- API Design : Concept RESTful, verbes HTTP (GET/POST/PUT/DELETE), codes status (200/201/400/404)
- Doctrine Relations : Modélisation N:N (bidirectionnelle), cascade operations
- Filtrage avancé : Combinaison de filtres (search + range + order + property selection)
- Validations côté serveur : Annotations Symfony, messages d'erreur multilingues
- Sérialisation JSON : Groupes de sérialisation, relations imbriquées, HATEOAS
- Documentation auto-générée : Swagger UI explorable, OpenAPI schema complèt
- Gestion d'erreurs : Exceptions, codes HTTP appropriés, détails validation
💻 Exemple de requête API
- GET /api/livres?titre=harry&ordre[prix]=DESC&properties[]=isbn&properties[]=titre&properties[]=prix
- Response: [{ "isbn": "0747532699", "titre": "Harry Potter 1", "prix": 25.99, "@id": "/api/livres/1" }, ...]
📖 Documentation & Outils
- Swagger UI : GET /api → interface interactive pour tester tous les endpoints
- OpenAPI Schema : GET /api/docs.json → spécification complète pour génération clients
- HATEOAS : Chaque réponse inclut liens vers ressources liées
- Error Responses : Format standard (hydra:description, hydra:title, détails validation)
- Content Negotiation : JSON-LD par défaut, extensible (CSV, XML via custom encoders)
🤝 Apprentissage & Contexte
- TP Classroom : Distributed via GitHub Classroom (chaque étudiant = repo perso)
- PHP 8.2 en Codespaces : Environnement cloud GitHub, zéro configuration locale
- DB Externe : MySQL hébergé sur serveur BTS (btssio.dedyn.io)
- Migrations Doctrine : Versionnage de schema, reproductibilité
- Best Practices : Validations strictes, erreurs détaillées, documentation claire
Cet API Platform démontre une compréhension profonde des APIs RESTful modernes : zero-code CRUD, filtres déclaratifs, validations robustes, et documentation auto-générée. C'est la quintessence d'une API production-ready.
