API Resources et DTOs
Statut
Document de cadrage backend — version initiale.
État actuel
Aucun dossier Resources Laravel généralisé n'est visible dans api/app/Modules.
Le projet utilise en revanche de nombreux DTOs dans les modules :
ActeurDTOPublicationDTOCommuneDTOCurrentUserStats*DTOPlayLoop*DTOAssoSuite*DTOMairie*DTO
Ces DTOs jouent aujourd'hui le rôle de format de sortie ou d'objet de transfert.
Objectif
Les réponses API doivent être stables, explicites et sécurisées.
Elles ne doivent pas exposer par accident :
- champs sensibles ;
- identifiants techniques inutiles ;
- données de paiement ;
- tokens ;
- champs internes de modération.
DTO vs API Resource
| Option | Avantage | Limite |
|---|---|---|
| DTO | Explicite, typé, indépendant d'Eloquent. | Peut nécessiter plus de code manuel. |
| API Resource Laravel | Standard Laravel, pratique pour sérialiser. | Peut rester trop proche des modèles si mal utilisée. |
Convention actuelle
Tant que les DTOs sont utilisés, ils doivent :
- être explicites ;
- éviter les champs sensibles ;
- implémenter un format stable ;
- exposer uniquement ce qui est utile ;
- distinguer lecture publique et lecture interne.
Vision cible
Le projet doit choisir une convention officielle :
- conserver les DTOs ;
- adopter API Resources ;
- ou combiner DTOs pour le métier et Resources pour l'HTTP.
Le choix doit être documenté avant d'introduire une nouvelle couche.
Exemple de règle
Un champ sensible comme un identifiant Stripe ne doit jamais être exposé dans une réponse publique.
Cette règle est déjà visible dans les commentaires et choix du DTO acteur.
Points à clarifier
- Convention de pagination.
- Format des erreurs.
- Format des collections.
- Versioning des réponses.
- DTOs publics vs administrateurs.