Migration de REST à GraphQL : Retour d'expérience technique avec PHP et JavaScript

Après avoir modernisé plusieurs projets legacy ces dernières années, j'ai réalisé que l'architecture REST montrait ses limites face à des besoins clients évolutifs. Dans cet article, je partage mon approche concrète pour migrer progressivement une API existante vers GraphQL, en combinant PHP côté backend et JavaScript côté frontend.

Pourquoi remplacer REST par GraphQL ?

La sur-fetching chronique (récupérer trop de données) et la sous-fetching (trop d'appels API) coûtaient cher en performance. Un tableau de bord avec React nécessitait parfois 12 requêtes REST différentes - un cauchemar en 4G lent 🐌.

GraphQL a résolu trois problèmes majeurs :

• Flexibilité des requêtes côté client
• Réduction du nombre d'appels API
• Typage strict pour des contrats API fiables

Mais attention : la migration doit être incrémentale pour ne pas bloquer les équipes !

Phase 0 : Audit et plan de migration

J'ai commencé par cartographier toutes les routes REST existantes (une centaine) en les catégorisant :

1. Endpoints à fort trafic (prioritaires)
2. Fonctionnalités critiques (paiement, authentification)
3. Services internes (peu impactés)

L'outil GraphQL Mesh nous a permis de wrapper des APIs REST existantes pendant la transition. Une stratégie hybride temporaire où :

// Exemple d'adaptateur PHP (Symfony)
class UserResolver {
    #[Query]
    public function getUser(int $id): User
    {
        // Appel au legacy REST interne
        return $this->restClient->get('/api/v1/users/'.$id);
    }
}

Backend PHP : Construire le schéma pas à pas

Avec webonyx/graphql-php, j'ai structuré le schéma en domaines fonctionnels. Clé de succès : ne pas tout réécrire d'un coup !

Étape clé : Versionnement intelligent

Plutôt que de versionner l'API, j'ai utilisé des directives GraphQL pour gérer les évolutions :

type User @deprecated(reason: "Utiliser Account depuis 2025") {
    email: String!
    login: String! @rename(newname: "username")
}

Intégration des résolveurs

Chaque résolveur PHP se connecte soit :

• Au legacy REST (transition)
• À un nouveau service gRPC
• Directement à la base de données pour les modules modernisés

Le dataloader intégré réduit les requêtes N+1 grâce à du batch processing intelligent 🚀.

Frontend JavaScript : Optimisation drastique

Avec Apollo Client dans notre stack React, le gain fut immédiat. Une seule requête remplace 7 appels REST antérieurs :

const DASHBOARD_QUERY = gql`
  query Dashboard($userId: ID!) {
    user(id: $userId) {
      ...ProfileSection
      ...RecentOrders
      ...PersonalizedRecommendations
    }
  }
`;

Gestion du cache : Le game-changer

Apollo Cache normalise les données automatiquement. Pour optimiser :

• Identifiants uniques dans les types GraphQL
• Policies de cache personnalisées
• Optimistic UI pour les mutations

const [updateProfile] = useMutation(UPDATE_PROFILE, {
  optimisticResponse: {
    __typename: 'Mutation',
    updateProfile: {
      __typename: 'User',
      id: userId,
      name: 'Nouveau nom'
    }
  },
  update(cache) {
    // Mise à jour immédiate du UI
  }
});

Performances : Ce que nous avons mesuré

• ⏱️ 68% de réduction du temps de chargement sur mobile
• 📉 40% moins d'erreurs réseau
• 🔋 Jusqu'à 3x moins de batterie consommée (via requêtes optimisées)

Le secret ? Combiner :

• Persisted queries (enregistrement côté serveur)
• Automatic query batching
• Cache HTTP CDN pour les données publiques

FAQ : Mes pièges à éviter

Faut-il abandonner REST d'un coup ?
Non ! Utilisez un proxy GraphQL qui agrège REST et nouveaux endpoints.

Comment convaincre l'équipe ?
Commencez par un POC sur un microservice non critique. Les développeurs frontend vont adopter 💡.

Quel impact sur le monitoring ?
Prévoyez des outils spécifiques (Apollo Studio, GraphQL Inspector) pour tracer les performances.

Cette migration fut un marathon, pas un sprint. La clé ? Adapter GraphQL à ses besoins plutôt que l'inverse. Aujourd'hui, notre stack hybride permet d'évoluer sereinement entre anciens et nouveaux systèmes.