Aller au contenu principal

Règles API

Statut​

Document de règles projet — version initiale.

Objectif​

Garantir une API DMV cohérente, versionnée, sécurisée et exploitable par toutes les applications connectées.

Règles strictes​

  • Toutes les routes métier doivent être versionnées sous /api/v1.
  • Les erreurs API doivent rester en JSON.
  • Les mutations sensibles doivent vérifier authentification, autorisation et périmètre.
  • Le header X-App-Source doit être utilisé quand la route dépend de l'application appelante.
  • Ne pas exposer de champs internes, tokens ou secrets.
  • Ne pas créer d'endpoint sans responsabilité claire.
  • Ne pas casser un contrat API sans stratégie de migration.

Sources applicatives​

Sources visibles et admises :

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

Structure de réponse​

Recommandation :

  • envelopper les ressources principales avec un nom explicite ;
  • exposer des listes paginées quand le volume peut croître ;
  • inclure des statuts compréhensibles ;
  • garder les erreurs actionnables.

Autorisation​

Chaque mutation doit répondre à trois questions :

  • qui appelle ?
  • depuis quelle application ?
  • sur quel périmètre agit-il ?

Exemples de périmètre :

  • acteur ;
  • commune ;
  • association ;
  • device ;
  • admin global ;
  • utilisateur propriétaire.

Versioning​

  • v1 est la version visible.
  • Les changements compatibles restent dans v1.
  • Les changements destructifs doivent être préparés.
  • Les routes obsolètes doivent être documentées avant retrait.

Anti-patterns​

  • Route admin accessible sans middleware strict.
  • Réponse différente selon exception non contrôlée.
  • Payload trop large.
  • Endpoint misc ou doStuff.
  • Logique métier dupliquée par application.
  • Accès direct frontend à la donnée pour contourner l'API.

Points à clarifier​

  • Documentation OpenAPI ou équivalent.
  • Convention exacte d'erreur.
  • Pagination standard.
  • Dépréciation d'API.
  • Contrats inter-applications.