Conventions API

Objectif

Définir un langage commun pour les contrats API DMV afin de garder des échanges stables entre applications.

Versioning API

État visible :

• Les modules Laravel sont montés sous le préfixe api/v1.
• Les routes visibles utilisent donc le format /api/v1/....

Convention cible :

• Toute nouvelle route métier publique ou applicative doit rester sous /api/v1.
• Une rupture de contrat majeure devra passer par une future version /api/v2.

Format standard succès

Format cible proposé :

{
  "data": {},
  "meta": {}
}

Pour une collection :

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 15,
    "total": 42
  }
}

Healthchecks

Routes confirmées pour supervision légère :

Route	Usage	Dépendances
GET /health	Healthcheck racine public.	Pas d'accès DB obligatoire, pas d'appel externe.
GET /api/health	Healthcheck API public.	Pas d'accès DB obligatoire, pas d'appel externe.
GET /up	Healthcheck Laravel natif.	Comportement Laravel conservé.
GET /api/v1/health	Healthcheck v1 historique.	Conservé pour compatibilité.

Format attendu pour /health et /api/health :

{
  "status": "ok",
  "service": "dmv-api",
  "timestamp": "2026-05-10T10:00:00+00:00"
}

Format standard erreur

État visible :

• identify.app renvoie déjà error, message et allowed pour les erreurs X-App-Source.

Format cible proposé :

{
  "error": "validation_failed",
  "message": "La requête est invalide.",
  "details": {
    "field": ["Message explicite."]
  }
}

Codes erreurs

Code HTTP	Usage
400	Requête invalide ou header applicatif absent/inconnu.
401	Authentification absente ou invalide.
403	Authentifié mais non autorisé.
404	Ressource inexistante ou non visible dans le scope.
409	Conflit métier ou idempotence.
422	Validation métier ou formulaire.
429	Rate limit dépassé.
500	Erreur serveur non prévue.

Pagination

Convention cible :

• Paramètres : page, per_page.
• Valeur par défaut recommandée : 15 ou 20 selon ressource.
• Maximum à confirmer par ressource.

Exemple :

GET /api/v1/publications?page=1&per_page=15
X-App-Source: dmv

Tri et filtres

Convention cible :

• sort pour le champ de tri.
• direction avec asc ou desc.
• Filtres explicites par domaine : commune_id, acteur_id, status, type, q.
• Les filtres doivent être validés côté Laravel.

Validation

• La validation doit être effectuée côté Laravel.
• Les frontends peuvent pré-valider l’UX, mais pas porter la règle métier finale.
• Les messages d’erreur doivent rester lisibles et stables.

Idempotence

Obligatoire ou fortement recommandée pour :

• webhooks ;
• paiements ;
• souscriptions ;
• boosts ;
• opérations sensibles pouvant être rejouées.

Header cible proposé :

Idempotency-Key: <uuid-ou-cle-client>

Uploads

Convention cible :

• Upload multipart ou URL signée selon stockage final.
• Validation type, taille et droits côté Laravel.
• Pas de fichier exécutable accepté.
• Les médias doivent être rattachés à un objet métier.

Webhooks

• Les webhooks ne doivent pas dépendre de X-App-Source.
• La signature provider est obligatoire.
• Le traitement doit être idempotent.
• Le payload brut peut être nécessaire pour vérifier la signature.

Rate limiting

À appliquer selon criticité :

• auth et exchange ;
• claims ;
• reports ;
• uploads ;
• IA ;
• webhooks ;
• endpoints device PlayLoop.

CORS

État à valider par environnement :

• Access-Control-Allow-Origin: * facilite les tests mais doit être évité en production si l'API reçoit des credentials ou des tokens navigateur.
• Origines production cibles : https://dansmonvillage.fr et https://www.dansmonvillage.fr.
• Les previews Cloudflare Pages peuvent être autorisées seulement si nécessaires, via une règle explicite et documentée.
• Tout durcissement CORS doit être coordonné avec les frontends pour éviter une rupture applicative.

Cache

• Lecture publique cacheable si la donnée est non sensible.
• Données privées, droits, paiements, IA et administration non cacheables publiquement.
• Les caches doivent respecter le scope X-App-Source.

Headers importants

Header	Statut	Usage
X-App-Source	Confirmé	Source applicative : dmv, backoffice, playloop, assosuite, mairie.
Authorization	Confirmé	Token Bearer pour routes Sanctum ou provider validé.
Idempotency-Key	Cible	Rejeu sécurisé des opérations sensibles.
Authorization (device)	Confirmé	Token opaque device PlayLoop via Bearer {device_token} — même header que Sanctum, middleware device.token.

Conventions dates

• Format cible : ISO 8601 UTC.
• Exemple : 2026-05-10T10:00:00Z.
• Les affichages locaux relèvent des frontends.

Conventions UUID/id

• Le code visible utilise parfois {id}, {slug}, {userId}.
• Le choix UUID vs entier doit être clarifié par modèle.
• Les URLs ne doivent pas exposer d’identifiants sensibles si cela crée un risque métier.

Conventions RBAC

• Le header X-App-Source donne un contexte, pas un droit.
• Les droits doivent être vérifiés côté Laravel.
• Les scopes attendus : utilisateur, acteur, commune, app source, admin global.
• Les actions sensibles doivent être auditables.

RBAC acteur V1.1

• Source d’autorité : acteur_collaborateurs + acteur_roles + acteur_permissions + acteur_role_permissions + acteur_modules.
• user_acteurs n’est plus qu’une projection de compatibilité workspace ; il ne doit pas être utilisé comme autorité RBAC métier.
• Un contrôle complet peut dépendre de deux axes distincts :
  • permission
  • module actif
• Exemple : un accès peut posséder manage_services, mais rester refusé si le module services est inactif.

Hiérarchie minimale côté serveur

• platform_admin : bypass contrôlé
• owner : contrôle total sur l’acteur
• admin : gestion standard, sans promotion en owner ni modification d’un owner
• editor / publisher / viewer : pas de gestion des collaborateurs

Principe de cohérence

• une règle UI sans équivalent serveur n’est pas considérée comme une sécurité suffisante ; l’autorisation doit toujours être appliquée côté API.
• les middlewares métier (mairie.access, commune.manager, etc.) doivent converger vers la même source d’autorité RBAC acteur au lieu de maintenir des règles divergentes.