Développeur Symfony / API Platform freelance

Une API Platform démarre presque toujours bien. Trois attributs sur une entité, et on a une collection paginée, une documentation OpenAPI, du JSON-LD et une interface Swagger. C’est justement ce qui la rend traître : on va très vite au début, et on ne voit pas tout de suite le moment où le code a commencé à travailler contre l’équipe.

À l’agence, nous écrivons des API Symfony et API Platform depuis plusieurs versions majeures : sur des marketplaces, dans un studio de jeu vidéo, et aujourd’hui sur Animalink. Cet article s’adresse aux équipes qui se demandent s’il est temps de faire venir quelqu’un de l’extérieur, et ce qu’elles peuvent en attendre.

Les signes qu’une API a besoin d’un regard extérieur

Elle ralentit à mesure qu’elle grossit

Le symptôme classique : une collection qui répondait en 80 ms en répond en 2 secondes un an plus tard, sans que personne ait touché à son code. En cause, presque toujours, la sérialisation. Un groupe de normalisation un peu trop généreux embarque une relation, puis la relation de la relation, et Doctrine exécute une requête par ligne.

Les questions à se poser :

Combien de requêtes SQL déclenche votre collection la plus utilisée ? Le profiler Symfony le dit en un clic.
Vos groupes de sérialisation sont-ils pensés par opération, ou partagés entre la liste et le détail ?
Les filtres portent-ils sur des colonnes indexées ? La pagination est-elle active partout, avec une taille maximale ?
Le cache HTTP est-il configuré, ou chaque lecture repart-elle en base ?

Rien de tout cela n’est difficile à corriger. Ce qui est difficile, c’est de savoir par où commencer quand vingt ressources souffrent du même mal.

Les droits sont vérifiés au mauvais endroit

C’est le point qui nous inquiète le plus quand nous relisons une API. Le front masque le bouton « Supprimer » aux utilisateurs qui n’y ont pas droit, et l’équipe en conclut que la suppression est protégée. Elle ne l’est pas : n’importe qui peut envoyer la requête à la main.

API Platform donne pourtant les outils pour faire ça proprement, au bon endroit (documentation sécurité) :

security sur l’opération, évalué avant la désérialisation : qui a le droit d’appeler cet endpoint ?
securityPostDenormalize, évalué après : l’utilisateur a-t-il le droit d’écrire ces valeurs ? C’est là qu’on empêche un client de se réattribuer une commande en changeant un IRI.
security sur #[ApiProperty], pour qu’un champ sensible disparaisse de la réponse selon le lecteur.
Une extension Doctrine pour filtrer les collections : un utilisateur ne doit même pas voir passer les lignes qui ne sont pas les siennes.

Le cas typique d’oubli : l’opération Get est protégée, la GetCollection ne l’est pas, et un ?page=2 suffit pour lister les données des autres. Un test fonctionnel par rôle et par opération, c’est souvent ce qui manque.

Le contrat JSON-LD dérive

Le troisième signe est plus discret. Le front a commencé par consommer le JSON-LD tel quel : @id comme clé de cache, @type pour choisir l’affichage, la documentation Hydra pour savoir ce qui est permis (voir JSON-LD : le contrat que le front attendait). Puis les exceptions se sont accumulées : un endpoint maison qui renvoie du JSON nu, un champ calculé qui n’apparaît pas dans la documentation, une relation exposée en entier ici et en IRI là, un PATCH sur state qui fait office de workflow.

À la fin, le front ne peut plus se fier au contrat, et il le redit en dur. On a perdu l’intérêt principal d’API Platform sans s’en rendre compte. Le symptôme le plus fiable : les types TypeScript générés depuis l’OpenAPI ne correspondent plus à ce que l’API renvoie vraiment, et quelqu’un les corrige à la main.

Elle a pris du retard de version

Ce n’est pas un symptôme, c’est une échéance. API Platform 4.4 et 5.0 sont sortis en septembre 2026, et la 5.0 ne supporte plus que Symfony 7.4 et 8 (annonce des Tilleuls). Côté Symfony, la 6.4 LTS ne reçoit plus de correctifs de bugs après novembre 2026, et plus de correctifs de sécurité après novembre 2027 (symfony.com).

Le projet passe en plus à une version majeure par an au lieu de tous les deux ans, et les filtres déclarés avec #[ApiFilter] sont dépréciés en 4.4. Le chemin recommandé est connu : passer en 4.4, corriger les dépréciations, puis monter en 5.0 en suivant le guide de migration. Il se fait bien quand l’API a des tests ; beaucoup moins bien quand elle n’en a pas.

Personne n’ose plus toucher au modèle

Le dernier signe est humain. Une ressource porte quarante propriétés, trois rôles différents la lisent, et chaque évolution casse quelque chose ailleurs. C’est souvent un problème de découpage : une même entité qui devrait être exposée sous plusieurs ressources, une jointure qui porte une donnée et mériterait d’être une ressource à part, une transition métier écrite comme une simple écriture de champ. La règle que nous appliquons est détaillée dans Découper un domaine métier en ressources API Platform : séparer deux ressources quand elles diffèrent sur qui les écrit, qui les lit, et à quel rythme elles changent.

Ce que couvre une mission

Selon ce qui inquiète l’équipe, une mission prend une ou plusieurs de ces formes.

Un audit de l’API

C’est souvent le point de départ, et parfois tout ce dont l’équipe a besoin. Nous lisons le code, exécutons l’API, la testons comme le ferait quelqu’un de mal intentionné, et rendons un rapport classé par gravité et par effort :

droits vérifiés opération par opération, et collection par collection ;
performance des requêtes sur les ressources les plus sollicitées ;
cohérence du contrat : documentation OpenAPI et Hydra contre réponses réelles ;
dépendances, versions en fin de vie et chemin de migration ;
couverture de tests sur ce qui compte vraiment.

Compter de trois jours pour une API ou un module à deux semaines pour une application complète avec son infrastructure. Le détail est sur la page Audit de sécurité et de qualité.

Une refonte de ressources

Quand l’audit montre que le problème est structurel, on reprend le découpage : plusieurs #[ApiResource] sur une même classe pour séparer les points de vue (public, client, professionnel), des opérations nommées avec leur DTO d’entrée et leur processor pour les transitions métier, des groupes de sérialisation par opération. On avance ressource par ressource, avec des tests qui figent le comportement actuel avant de le changer, pour que le front ne casse pas en route.

De la documentation qui sert

Une API Platform se documente en grande partie toute seule, à condition qu’on l’y aide. Des description sur les propriétés et les opérations, des exemples, des opérations personnalisées correctement déclarées : la documentation générée devient alors la vraie référence, pour les développeurs front, pour les partenaires qui intègrent l’API, et de plus en plus pour les agents LLM qui la pilotent. Nous y ajoutons en général une page d’architecture courte : les ressources, leurs lecteurs, les règles de droits.

Un front React branché sur le contrat

C’est là que le travail sur l’API rapporte. Une fois le contrat propre, le back-office n’a plus besoin d’être écrit écran par écran. L’agence publie pour ça react-resource-view : on déclare une ressource une fois, et le package génère sa liste, son détail, ses formulaires de création et d’édition et la confirmation de suppression, câblés à l’API et à l’URL.

npx react-resource-view init mon-admin -b api-platform -u https://localhost

const articles = createViewResource<Article>("articles", {
  name: "Articles",
  path: "/api/articles",
  form: { inputs: { title: { label: "Titre" }, body: { label: "Texte" } } },
})

Les écrans métier, ceux qui ont une règle tordue ou qui agrègent cinq ressources, restent écrits à la main. Les autres sortent de la déclaration, et suivent l’API quand elle évolue.

Comment on travaille ensemble

Forfait ou régie

Les deux existent, et le choix dépend de ce qu’on sait au départ :

Le forfait pour un périmètre fermé : un audit, une montée de version, la refonte d’un module identifié. Le prix est fixé avant de commencer, le livrable aussi.
La régie, facturée au jour, pour un chantier ouvert ou un renfort d’équipe : quand on découvre le travail en le faisant, ou qu’on veut un développeur senior dans l’équipe pendant quelques semaines.

Un schéma fréquent : un audit au forfait, puis une régie pour corriger ce qu’il a trouvé, avec un plan déjà priorisé.

À Lyon ou à distance

L’agence est à Lyon. La plupart des missions se font à distance, avec des points réguliers et une pull request relue par lot. Nous nous déplaçons volontiers pour le cadrage ou les ateliers de modélisation : c’est là qu’une heure autour d’un tableau en économise dix sur un ticket.

Comment ça commence

Par un premier échange d’une heure, gratuit et sans engagement : ce que fait l’API, ce qui vous inquiète, ce que vous avez déjà essayé. Nous en tirons une proposition écrite, avec un périmètre, un découpage en lots, une estimation et le mode de facturation. Si l’API n’a pas besoin de nous, nous le disons.

Pour un projet neuf ou une évolution, tout est décrit sur la page Développement web sur mesure. Pour un regard sur l’existant, c’est la page Audit de sécurité et de qualité. Et pour en parler directement, la page Contact.