Une API Symfony au cœur d’un service de mobilité solidaire

Cet article ouvre une série consacrée à l’API REST de Rezo Pouce, le composant central de l’écosystème technique présenté dans l’article d’introduction. Les articles suivants détailleront l’authentification et le contrôle d’accès, le service Rezo Séniors côté API, et le géocodage, les documents et l’import de données.

Le cœur du système

Dans l’écosystème Rezo Pouce, l’API hébergée à api.rezopouce.fr n’est pas un simple intermédiaire — c’est le seul composant qui accède à la base de données. Toutes les applications — site public, espace d’inscription, back-office d’administration, partenaire Mobicoop — passent par elle pour lire ou modifier des données.

Ce choix architectural centralise la logique métier à un seul endroit. Changer une règle de gestion, ajouter une validation, ajuster un calcul : une seule intervention, un seul déploiement, quel que soit le nombre de clients qui consomment l’information.

Pourquoi Symfony

Symfony a été retenu pour ses qualités éprouvées en contexte professionnel : structure claire, injection de dépendances, système de routing robuste et écosystème de bundles mature. La sérialisation des réponses, la validation des entrées et la gestion des erreurs HTTP s’appuient sur les composants natifs du framework.

La base de données est MariaDB, pilotée par Doctrine ORM. La sérialisation repose sur JMS Serializer avec des groupes d’exclusion configurables — un même objet produit des réponses JSON différentes selon le contexte d’appel. Les erreurs suivent un format JSON standard avec codes HTTP conventionnels (200, 201, 400, 401, 403, 404, 500).

Une architecture en bundles

L’API est organisée en cinq bundles, chacun responsable d’un domaine fonctionnel :

• APIBundle — le cœur : utilisateurs, territoires, communes, points d’arrêt, statistiques, fiches mobilité, import de données.
• SeniorsBundle — le service Rezo Séniors : gestion des trajets, mise en relation conducteurs/passagers, conducteurs solidaires, notifications.
• GeocodeBundle — les services géographiques : géocodage, autocomplétion d’adresses, calcul d’itinéraires.
• MailBundle — les notifications : emails transactionnels et SMS via l’API OVH.
• DocumentBundle — la gestion documentaire : upload, stockage typé, vignettes, génération de PDF.

Cette organisation n’est pas qu’un choix de rangement — elle reflète des périmètres fonctionnels indépendants. Le SeniorsBundle, par exemple, possède ses propres entités, ses propres services et ses propres routes, et peut évoluer sans impacter la gestion des territoires.

Servir quatre clients avec des besoins différents

L’API expose deux familles de routes : les routes frontend, publiques et en lecture seule, consommées par le site public ; et les routes backend, protégées et complètes, consommées par les espaces d’administration.

Un même concept — un territoire, un point d’arrêt, un utilisateur — n’est pas exposé de la même manière selon le consommateur. Le site public a besoin du nom et de la carte d’un territoire. Le back-office a besoin de sa configuration complète, de ses gestionnaires, de ses paramètres Séniors, de ses statistiques. Les groupes de sérialisation JMS gèrent cette différenciation : un même objet Doctrine, sérialisé avec un groupe différent, produit une réponse adaptée au consommateur sans duplication de code.

Ce découplage entre la représentation interne et les réponses exposées est ce qui a permis à l’API de servir quatre clients aux besoins très différents pendant cinq ans, sans multiplier les endpoints ni dupliquer la logique.

Ce que cette série détaille

Les articles suivants entrent dans les aspects les plus structurants de cette API :

• L’authentification et le contrôle d’accès — double mécanisme (token opaque pour le site public, JWT avec délégation Mobicoop pour l’administration), hiérarchie de droits à trois niveaux, sécurisation par route.
• Le service Rezo Séniors — l’algorithme de mise en relation conducteurs/passagers, les classes de délai, les notifications multi-canal (email et SMS), les tâches planifiées.
• Géocodage, documents et import de données — l’architecture hexagonale du GeocodeBundle, le stockage typé de documents, la génération de PDF, l’import CSV et la synchronisation événementielle avec Mobicoop.

Concevoir une API qui sert simultanément plusieurs applications de natures différentes — un site Symfony, deux SPA Angular, une SPA AngularJS, un partenaire externe — oblige à penser les contrats d’interface avec soin. Un endpoint mal conçu, trop couplé à l’interface qui l’a motivé, devient rapidement un frein pour les autres consommateurs. Sur cinq ans, l’API a évolué en parallèle des applications front, tout en maintenant la compatibilité avec les versions existantes. C’est un exercice de rigueur qui développe une sensibilité particulière à la stabilité des interfaces et à l’impact de chaque décision technique sur l’ensemble du système.