Aller au contenu principal

Architecture API

Statut​

Document de cadrage architecture — version initiale.

Vue d'ensemble​

L'API DMV est une API Laravel modulaire. Elle expose une version v1 et charge les routes métier via les ServiceProviders des modules.

La cible est d'en faire la couche métier commune de l'écosystème : DMV public, backoffice, PlayLoop, AssoSuite, Mairie et futures applications.

État actuel visible​

  • api/routes/api.php contient le health-check /api/v1/health.
  • Les routes métier sont chargées par les ServiceProviders des modules.
  • Les modules utilisent un préfixe api/v1.
  • Les réponses d'erreur sont forcées en JSON dans api/bootstrap/app.php.
  • Des middlewares applicatifs sont déclarés : identify.app, ensure.admin, device.token, asso.access, mairie.access.
  • L'authentification API utilise Laravel Sanctum.

Convention d'URL​

La convention visible et cible :

/api/v1/auth/*
/api/v1/communes/*
/api/v1/acteurs/*
/api/v1/publications/*
/api/v1/admin/*
/api/v1/playloop/*
/api/v1/assosuite/*
/api/v1/mairie/*

Les chemins exacts doivent rester documentés par module.

Source applicative​

Le middleware identify.app utilise le header X-App-Source.

Sources acceptées visibles :

  • dmv ;
  • backoffice ;
  • playloop ;
  • assosuite ;
  • mairie.

Ce header permet de contextualiser les règles selon l'application appelante.

Principes API​

  • Les mutations doivent passer par l'API métier.
  • Les réponses doivent être structurées et cohérentes.
  • Les erreurs doivent rester JSON.
  • Les règles d'autorisation doivent être côté backend.
  • Les modules doivent exposer des endpoints lisibles et versionnés.
  • Les frontends ne doivent pas réimplémenter les règles métier.

Supabase et API​

Des accès Supabase sont encore visibles dans les frontends et migrations.

La cible est de clarifier progressivement :

  • ce qui reste lu directement ;
  • ce qui doit transiter par l'API ;
  • quelle couche porte les règles métier ;
  • quelle source gouverne les migrations et schémas.

Risques et points à clarifier​

  • Contrats de réponse à formaliser pour les apps.
  • Gestion d'erreurs transverse à stabiliser.
  • Politique CORS et sources autorisées à maintenir.
  • Documentation OpenAPI ou équivalent à prévoir.
  • Migration progressive des accès directs Supabase à cadrer.