Angular Graphql Apollo-Angular Apollo-Client Typescript Graphql-Codegen Queries Mutations Cache-Normalise Gestion-Erreurs Pagination Subscriptions Front-End Api-Typee

Intégrez Apollo Angular à une API GraphQL : queries et mutations typées, codegen automatique, cache normalisé, pagination et subscriptions en temps réel.

Sommaire

- GraphQL face à REST : ce qui change pour Angular
- Installer et configurer Apollo Angular
- Générer des types TypeScript avec GraphQL Code Generator
- Queries typées avec Apollo et RxJS
- Fragments GraphQL : réutiliser les sélections de champs
- Mutations : écrire et mettre à jour le cache
- Cache normalisé : InMemoryCache et politiques
- Pagination cursor-based et subscriptions temps réel
- Gestion des erreurs, retries et tests

GraphQL face à REST : ce qui change pour Angular Avec REST, chaque écran Angular multiplie souvent les appels HTTP pour assembler ses données : un appel pour l'utilisateur, un autre pour ses commandes, un troisième pour les produits associés. GraphQL inverse la logique — le client décrit exactement les champs dont il a besoin dans une seule requête, et le serveur répond avec une structure JSON qui correspond point par point à cette demande.

Ce changement de paradigme a un impact direct sur l'architecture Angular. Les services qui, en REST, orchestraient plusieurs appels HTTP avec forkJoin ou des switchMap imbriqués se simplifient : une seule query GraphQL remplace souvent trois ou quatre requêtes REST chaînées. Le code d'agrégation manuelle — qui était une source fréquente de bugs de synchronisation et de race conditions — disparaît purement et simplement, puisque c'est le serveur GraphQL qui résout le graphe de données en une seule passe.

Cette approche déplace aussi la responsabilité du modelage des données. En REST, c'est l'équipe backend qui décide de la forme des réponses ; en GraphQL, c'est le frontend Angular qui décide, requête par requête, des champs à récupérer. Pour une équipe qui livre plusieurs clients (application web Angular, application mobile, tableau de bord interne), cela évite de multiplier les endpoints REST « sur-mesure » (/api/orders/summary, /api/orders/detail…) qui finissent par diverger avec le temps.

À retenir : GraphQL ne remplace pas HttpClient — il s'appuie dessus. Apollo Angular envoie ses requêtes en POST vers un unique endpoint (généralement /graphql), avec la query et les variables dans le corps de la requête.

Concrètement, une vue « détail commande » qui nécessitait 3 appels REST devient une seule requête GraphQL :

query GetOrderDetail($orderId: ID!) { order(id: $orderId) { id status total customer { name email } items { productName quantity unitPrice } } }

Ce Modèle Réduit L'over-fetching (récupérer Des Champs Inutilisés) Et L'under-fetching (devoir Enchaîner Plusieurs Appels). Voici Les Différences Clés à Connaître Avant D'intégrer GraphQL Dans Une App Angular Existante

Critère REST GraphQL Endpoints Multiples (un par ressource) Unique (/graphql) Forme de la réponse Fixe côté serveur Définie par le client Sur-fetching / sous-fetching Fréquent Éliminé par design Typage bout-en-bout Manuel (DTO, OpenAPI) Généré depuis le schéma (codegen) Cache HTTP navigateur Natif (GET + ETag) Géré par Apollo (InMemoryCache)

Dans une app Angular, l'intégration se fait via Apollo Angular , le client officiel qui expose des Observable — s'intégrant naturellement avec RxJS, les async pipes et, plus récemment, les Signals via toSignal().

Installer et configurer Apollo Angular

L'installation se fait en trois paquets : le client Apollo lui-même, le binding Angular, et la librairie GraphQL de référence pour le parsing des documents.

Installer Apollo Angular et ses dépendances npm install apollo-angular @apollo/client graphql

Depuis Angular 15+, la configuration se fait sans NgModule, directement dans app.config.ts via ApplicationConfig : // src/app/app.config.ts import { ApplicationConfig } from '@angular/core'; import { provideHttpClient } from '@angular/common/http'; import { InMemoryCache } from '@apollo/client/core'; import { provideApollo } from 'apollo-angular'; import { provideHttpLink, HttpLink } from 'apollo-angular/http'; import { inject } from '@angular/core'; export const appConfig: ApplicationConfig = { providers: [ // Angular a besoin de HttpClient pour transporter les requêtes GraphQL provideHttpClient(), // Expose HttpLink, le transport HTTP utilisé par Apollo provideHttpLink(), // Configure le client Apollo lui-même provideApollo(() => { const httpLink = inject(HttpLink); return { // Endpoint unique du serveur GraphQL link: httpLink.create({ uri: 'https://api.mon-site.com/graphql' }), // Cache normalisé — voir section dédiée plus bas cache: new InMemoryCache(), defaultOptions: { watchQuery: { // Retourne le cache en attendant la réponse réseau fetchPolicy: 'cache-and-network' } } }; }) ] };

Pour ajouter l'authentification (token JWT dans les headers), on compose un second lien avec ApolloLink :

// Ajouter le header Authorization à chaque requête GraphQL import { ApolloLink } from '@apollo/client/core'; import { setContext } from '@apollo/client/link/context'; const authLink = setContext((_, { headers }) => { const token = localStorage.getItem('access_token'); return { headers: { ...headers, // Le serveur GraphQL lit ce header pour authentifier la requête authorization: token ? `Bearer ${token}` : '' } }; }); // Dans provideApollo : chaîner authLink avant httpLink link: authLink.concat(httpLink.create({ uri: 'https://api.mon-site.com/graphql' }))

Note : Contrairement à HttpInterceptorFn pour REST, l'authentification GraphQL se configure via ApolloLink, une chaîne de middlewares propre à Apollo Client — les deux mécanismes ne se substituent pas l'un à l'autre.

Générer des types TypeScript avec GraphQL Code Generator

Écrire les interfaces TypeScript à la main pour chaque query est source d'erreurs et de désynchronisation avec le schéma serveur. GraphQL Code Generator lit le schéma distant et vos fichiers .graphql, puis génère automatiquement des types stricts.

Installer le CLI et le preset client Apollo npm install -D @graphql-codegen/cli @graphql-codegen/client-preset

Le fichier de configuration pointe vers le schéma distant et le dossier contenant vos opérations GraphQL : // codegen.ts — configuration à la racine du projet import type { CodegenConfig } from '@graphql-codegen/cli'; const config: CodegenConfig = { // Introspection du schéma depuis l'API GraphQL en dev schema: 'https://api.mon-site.com/graphql', // Où chercher les documents GraphQL (queries/mutations) documents: ['src/**/*.graphql'], generates: { './src/app/graphql/generated/': { // Preset client : génère types + hooks typés en une passe preset: 'client', plugins: [] } } }; export default config;

Vous écrivez ensuite vos opérations dans des fichiers .graphql dédiés, séparés du code TypeScript :

- src/app/graphql/get-order-detail.graphql query GetOrderDetail($orderId: ID!) { order(id: $orderId) { id status total customer { name email } } } # Lancer la génération (à ajouter dans package.json scripts) npx graphql-codegen --config codegen.ts # Mode watch pendant le développement npx graphql-codegen --config codegen.ts --watch

Gain concret : Le codegen génère un type GetOrderDetailQuery reflétant exactement la forme de la réponse. Si un champ est renommé côté serveur, le build Angular échoue immédiatement à la compilation — plus besoin d'attendre un bug en production. Queries typées avec Apollo et RxJS

Le service Apollo injectable expose watchQuery(), qui retourne un Observable se réactualisant automatiquement à chaque changement du cache — pas besoin de recharger manuellement après une mutation liée.

// src/app/services/order.service.ts import { Injectable, inject } from '@angular/core'; import { Apollo } from 'apollo-angular'; import { map } from 'rxjs/operators'; import { GetOrderDetailDocument, GetOrderDetailQuery } from '../graphql/generated/graphql'; @Injectable({ providedIn: 'root' }) export class OrderService { private apollo = inject(Apollo); // Retourne un Observable typé grâce au document généré par codegen getOrderDetail(orderId: string) { return this.apollo .watchQuery ({ query: GetOrderDetailDocument, variables: { orderId }, // Réutilise le cache immédiatement, revalide en arrière-plan fetchPolicy: 'cache-and-network' })



.valueChanges.pipe( // result.data est déjà typé — autocomplétion complète dans l'IDE map(result => result.data.order) ); } }

Côté Composant, On Consomme L'Observable Comme N'importe Quel Flux RxJS — Via Async Pipe Ou Converti En Signal Avec ToSignal()

// src/app/components/order-detail/order-detail.component.ts import { Component, inject, input } from '@angular/core'; import { toSignal } from '@angular/core/rxjs-interop'; import { OrderService } from '../../services/order.service'; @Component({ selector: 'app-order-detail', standalone: true, template: ` @if (order(); as o) {

Commande #{{ o.id }}

Statut : {{ o.status }} — Total : {{ o.total }}€

Client : {{ o.customer.name }} ({{ o.customer.email }})

} @else {

Chargement…

} ` }) export class OrderDetailComponent { private orderService = inject(OrderService); orderId = input.required (); // Convertit l'Observable Apollo en Signal — réactif sans souscription manuelle order = toSignal(this.orderService.getOrderDetail(this.orderId())); }

Pour une lecture ponctuelle sans abonnement continu (ex : chargement initial d'un formulaire), préférez query() qui retourne une Promise unique plutôt que watchQuery() :

// Lecture ponctuelle — pas de mise à jour automatique via le cache async loadOnce(orderId: string) { const result = await firstValueFrom( this.apollo.query ({ query: GetOrderDetailDocument, variables: { orderId } }) ); return result.data.order; }

Fragments GraphQL : réutiliser les sélections de champs

Dès qu'un même type (comme Order ou Customer) apparaît dans plusieurs queries — la liste des commandes, le détail d'une commande, l'historique client — dupliquer la sélection de champs à chaque fois devient vite ingérable. Les fragments GraphQL résolvent ce problème en définissant un ensemble de champs nommé et réutilisable, un peu comme un composant Angular réutilisable pour une portion d'UI.

- src/app/graphql/fragments/order-summary.graphql fragment OrderSummary on Order { id status total createdAt }

Ce fragment s'insère ensuite dans n'importe quelle query avec la syntaxe ...NomDuFragment :
- src/app/graphql/list-orders-with-fragment.graphql #import "./fragments/order-summary.graphql" query ListOrdersWithFragment { orders(first: 20) { edges { node { ...OrderSummary customer { name } } } } }

Summary Avec graphql-codegen, chaque fragment génère aussi son propre type TypeScript exportable (OrderSummaryFragment), que l'on peut utiliser pour typer des fonctions utilitaires ou des composants Angular partagés sans dépendre de la query complète qui les englobe : // src/app/components/order-card/order-card.component.ts import { Component, input } from '@angular/core'; import { OrderSummaryFragment } from '../../graphql/generated/graphql'; @Component({ selector: 'app-order-card', standalone: true, template: `

#{{ order().id }} {{ order().status }} {{ order().total }}€

` }) export class OrderCardComponent { // Le composant ne connaît que la forme du fragment, pas la query parente order = input.required (); }

Bénéfice architectural : Un composant Angular typé sur un fragment (plutôt que sur une query entière) peut être réutilisé dans n'importe quel écran qui inclut ce fragment — liste, détail, recherche — sans jamais avoir à retoucher son typage. C'est l'équivalent GraphQL du principe de composition de composants en Angular.

Mutations : écrire et mettre à jour le cache

Une mutation GraphQL modifie des données côté serveur. Sans intervention, le cache Apollo local ne sait pas qu'une entité a changé — il faut soit relancer une query, soit mettre à jour le cache manuellement pour éviter un aller-retour réseau superflu.

// src/app/graphql/update-order-status.graphql mutation UpdateOrderStatus($orderId: ID!, $status: OrderStatus!) { updateOrderStatus(orderId: $orderId, status: $status) { id status } } // src/app/services/order.service.ts (suite) import { UpdateOrderStatusDocument, UpdateOrderStatusMutation } from '../graphql/generated/graphql'; updateStatus(orderId: string, status: string) { return this.apollo.mutate ({ mutation: UpdateOrderStatusDocument, variables: { orderId, status }, // Met à jour immédiatement l'UI avant la réponse serveur (optimistic UI) optimisticResponse: { updateOrderStatus: { __typename: 'Order', id: orderId, status } }, // Fusionne le résultat dans le cache normalisé — pas de refetch réseau update: (cache, { data }) => { if (!data) return; cache.modify({ id: cache.identify({ __typename: 'Order', id: orderId }), fields: { status: () => data.updateOrderStatus.status } }); } }); }

Trois stratégies existent pour synchroniser le cache après une mutation, à choisir selon le contexte :

Stratégie Quand l'utiliser update() + cache.modify() Champ simple à corriger — le plus performant, zéro appel réseau refetchQueries Effet de bord complexe côté serveur (calculs dérivés, agrégats) cache.evict() + cache.gc() Suppression d'une entité (ex : mutation deleteOrder)

// Suppression : évincer l'entité du cache normalisé deleteOrder(orderId: string) { return this.apollo.mutate({ mutation: DeleteOrderDocument, variables: { orderId }, update: (cache) => { // Retire l'entité du cache sans requête supplémentaire cache.evict({ id: cache.identify({ __typename: 'Order', id: orderId }) }); // Nettoie les références orphelines restantes cache.gc(); } }); }

optimisticResponse : Utilisée ci-dessus, cette option met à jour l'UI instantanément avant la réponse serveur, puis Apollo réconcilie automatiquement avec la vraie réponse (ou annule en cas d'erreur). Idéal pour les actions perçues comme immédiates (like, changement de statut).

Cache normalisé : InMemoryCache et politiques

Contrairement à un cache HTTP classique qui stocke des réponses entières, InMemoryCache d'Apollo normalise les données : chaque entité (identifiée par __typename + id) est stockée une seule fois, quel que soit le nombre de queries qui la référencent.

// Configuration du cache avec des politiques de type import { InMemoryCache } from '@apollo/client/core'; const cache = new InMemoryCache({ typePolicies: { Order: { // Clé de cache personnalisée si l'ID n'est pas suffisant keyFields: ['id'], fields: { // Champ calculé côté client, jamais renvoyé par le serveur displayTotal: { read(_, { readField }) { const total = readField ('total') ?? 0; return `${total.toFixed(2)} €`; } } } }, Query: { fields: { // Politique de fusion pour la pagination (voir section suivante) orders: { keyArgs: ['filter'], merge(existing = [], incoming) { return [...existing, ...incoming]; } } } } } });

Cette normalisation explique pourquoi une mutation sur une commande affichée dans une liste met aussi à jour instantanément sa vue détail : les deux queries pointent vers la même entrée de cache , identifiée par Order:42.

Piège fréquent : Si votre schéma GraphQL n'expose pas de champ id sur un type, Apollo ne peut pas normaliser l'entité — elle est alors stockée en tant qu'objet imbriqué non partagé, avec les incohérences de cache que cela implique. Exposez toujours un id stable sur chaque type métier.

Le Comportement De Lecture Du Cache Dépend Aussi De La FetchPolicy Choisie Sur Chaque Query. C'est Un Réglage à Connaître Finement, Car Il Conditionne L'équilibre Entre Fraîcheur Des Données Et Nombre D'appels Réseau fetchPolicy Comportement cache-first (défaut) Retourne le cache si présent, sinon interroge le réseau cache-and-network Retourne le cache immédiatement, puis revalide en arrière-plan network-only Ignore le cache en lecture, mais le met à jour avec la réponse no-cache Ignore le cache en lecture ET en écriture cache-only Ne lit que le cache local, jamais le réseau

Pour un écran de type tableau de bord Angular affiché fréquemment, cache-and-network offre le meilleur compromis : l'utilisateur voit une donnée immédiatement (même périmée de quelques secondes), pendant que la requête réseau rafraîchit silencieusement le cache et met à jour la vue dès que la réponse arrive.

Pour inspecter le cache en développement, l'extension navigateur Apollo Client DevTools affiche l'arbre normalisé en temps réel et permet d'exécuter des queries directement depuis l'inspecteur.





Pagination cursor-based et subscriptions temps réel La pagination GraphQL suit généralement le pattern Relay cursor connections : chaque page expose des edges, un cursor par élément et un pageInfo.hasNextPage.

// src/app/graphql/list-orders.graphql query ListOrders($after: String) { orders(first: 20, after: $after) { edges { cursor node { id status total } } pageInfo { hasNextPage endCursor } } } // Charger la page suivante avec fetchMore() loadNextPage(queryRef: QueryRef , endCursor: string) { return queryRef.fetchMore({ variables: { after: endCursor } // La fonction merge() du typePolicy (section précédente) // s'occupe de concaténer les résultats automatiquement }); }

Pour les données temps réel (ex : suivi de commande en direct), Apollo Angular supporte les subscriptions via WebSocket, avec le même modèle de typage généré par codegen :

// src/app/graphql/order-status-changed.graphql subscription OrderStatusChanged($orderId: ID!) { orderStatusChanged(orderId: $orderId) { id status updatedAt } } // Configurer le transport WebSocket (graphql-ws) import { GraphQLWsLink } from '@apollo/client/link/subscriptions'; import { createClient } from 'graphql-ws'; import { split } from '@apollo/client/core'; import { getMainDefinition } from '@apollo/client/utilities'; const wsLink = new GraphQLWsLink( createClient({ url: 'wss://api.mon-site.com/graphql' }) ); // Route les subscriptions vers WebSocket, le reste vers HTTP const link = split( ({ query }) => { const definition = getMainDefinition(query); return definition.kind === 'OperationDefinition' && definition.operation === 'subscription'; }, wsLink, httpLink.create({ uri: 'https://api.mon-site.com/graphql' }) ); // Consommer la subscription dans un service Angular watchOrderStatus(orderId: string) { return this.apollo .subscribe ({ query: OrderStatusChangedDocument, variables: { orderId } }) .pipe(map(result => result.data?.orderStatusChanged)); }

Attention aux coûts : chaque subscription active maintient une connexion WebSocket ouverte. Désabonnez-vous systématiquement (takeUntilDestroyed()) quand le composant qui affiche le statut en temps réel est détruit, pour éviter les fuites de connexions côté serveur.

Gestion des erreurs, retries et tests

GraphQL renvoie toujours un statut HTTP 200, même en cas d'erreur métier — les erreurs apparaissent dans un tableau errors à côté de data. Il faut donc les intercepter explicitement, pas via un simple catchError HTTP.

// Middleware ApolloLink pour centraliser la gestion des erreurs import { onError } from '@apollo/client/link/error'; const errorLink = onError(({ graphQLErrors, networkError }) => { if (graphQLErrors) { // Erreurs métier renvoyées par le resolver GraphQL graphQLErrors.forEach(({ message, extensions }) => { console.error(`Erreur GraphQL: ${message}`, extensions); if (extensions?.['code'] === 'UNAUTHENTICATED') { // Rediriger vers le login si le token est expiré window.location.href = '/login'; } }); } if (networkError) { // Coupure réseau, timeout, 5xx serveur console.error(`Erreur réseau: ${networkError.message}`); } }); // Chaîner avant httpLink dans la configuration provideApollo link: errorLink.concat(authLink).concat(httpLink.create({ uri: '...' }))

Côté composant, l'Observable de watchQuery() expose aussi un champ errors directement dans chaque émission :

this.orderService.getOrderDetailRaw(orderId).subscribe({ next: (result) => { if (result.errors?.length) { // Erreurs partielles — certains champs ont pu être résolus quand même this.errorMessage = result.errors[0].message; } this.order = result.data.order; }, error: (err) => { // Erreur fatale (réseau, parsing) interceptée par errorLink en amont this.errorMessage = 'Impossible de charger la commande.'; } });

Pour les tests unitaires, apollo-angular/testing fournit un contrôleur de requêtes GraphQL analogue à HttpTestingController pour REST :

// order.service.spec.ts import { TestBed } from '@angular/core/testing'; import { ApolloTestingModule, ApolloTestingController } from 'apollo-angular/testing'; import { OrderService } from './order.service'; import { GetOrderDetailDocument } from '../graphql/generated/graphql'; describe('OrderService', () => { let service: OrderService; let controller: ApolloTestingController; beforeEach(() => { TestBed.configureTestingModule({ imports: [ApolloTestingModule], providers: [OrderService] }); service = TestBed.inject(OrderService); controller = TestBed.inject(ApolloTestingController); }); it('devrait récupérer le détail d'une commande', (done) => { service.getOrderDetail('42').subscribe(order => { expect(order?.status).toBe('SHIPPED'); done(); }); // Intercepte la query et répond avec des données mockées const op = controller.expectOne(GetOrderDetailDocument); op.flush({ data: { order: { id: '42', status: 'SHIPPED', total: 89.9, customer: { name: 'Ana', email: '[email protected]' } } } }); controller.verify(); }); });

Checklist avant mise en production

- Types générés via graphql-codegen intégrés au pipeline CI (fail si désynchronisés du schéma)
- errorLink centralisé pour intercepter erreurs métier et réseau
- typePolicies définies pour chaque type exposant une pagination
- Subscriptions désabonnées via takeUntilDestroyed()
- optimisticResponse utilisée uniquement sur des mutations à faible risque de conflit
- Tests avec ApolloTestingController couvrant queries, mutations et erreurs
- Champ id exposé sur chaque type métier pour garantir la normalisation du cache

Bilan : Apollo Angular n'ajoute pas de complexité pour ajouter de la complexité — il remplace le RxJS artisanal habituellement écrit pour agréger plusieurs appels REST par un modèle déclaratif typé de bout en bout, avec un cache qui se met à jour tout seul. Précédent Angular : oubliez $any(), utilisez l'optional chaining

Angular Any Optional-Chaining

Suivant Angular hostDirectives : composer ses directives

Angular Host-Directives Directive-Composition-Api

Sources et références officielles

- Apollo Angular — Documentation officielle — The Guild
- GraphQL Code Generator — Guide Angular — The Guild
- Introduction to GraphQL — GraphQL.org
- Angular — Documentation officielle — Angular (Google)

Questions fréquentes Installez les paquets avec `npm install apollo-angular @apollo/client graphql`, puis configurez `provideApollo()` dans `app.config.ts` avec l'URI de votre endpoint GraphQL via `provideHttpLink()`. Aucun module supplémentaire n'est requis pour les projets standalone Angular récents.

GraphQL est pertinent quand votre app affiche des vues composées de plusieurs ressources (over-fetching REST), ou quand plusieurs clients (web, mobile) ont besoin de champs différents. Pour un CRUD simple à une seule ressource, REST reste plus léger.

Utilisez `@graphql-codegen/cli` avec le preset `client` : il lit vos fichiers `.graphql` et votre schéma distant, puis génère des types TypeScript et des hooks `Query`/`Mutation` typés, éliminant toute saisie manuelle d'interfaces.

Trois options : `refetchQueries` pour relancer une query précise, `update()` pour modifier manuellement le cache normalisé, ou `cache.evict()` + `cache.gc()` pour invalider une entité. Privilégiez `update()` pour éviter des appels réseau superflus.

Publié/Développé par Mezgani Said

Développeur web full‑stack et formateur spécialisé en Angular, TypeScript et Node.js, il partage sur AngularForAll des ressources complètes pour les développeurs : tutoriels pratiques, guides pas‑à‑pas, outils gratuits, exercices, QCM techniques et retours d’expérience issus de projets réels (SaaS, micro‑frontends, architectures modulaires, applications d’entreprise).

Le site couvre l’ensemble de l’écosystème web : front‑end, intégration HTML/CSS, Composants réutilisables, SEO, back‑end, cloud, IA, CLI, productivité, bien‑être, outils web et métiers du digital.

Un espace pensé pour générer, apprendre, progresser et développer des projets modernes avec des bonnes pratiques professionnelles.

Partager

LinkedIn Facebook Twitter / X Pinterest WhatsApp TikTok Email

URL copiée dans le presse-papiers !

Voir aussi

Front

Angular hostDirectives : composer ses directives

Front

Angular : oubliez $any(), utilisez l'optional chaining

Front

Angular 2026 : tendances et sujets recherchés

Front

Angular 22 : OnPush par défaut, le guide pratique

Front

Angular FormArray : formulaires dynamiques

Front

Migration Angular 21 vers 22 : guide pas à pas

Front

Angular 22 : composants selectorless expliqués

Front

Angular + Tailwind CSS 4 : intégration complète

Front

Angular 20 : toutes les nouveautés

Front

Architecture Angular/Node.js : Clean, DDD, SOLID

📌 Angular + Apollo GraphQL : requêtes typées (Front)
🏢 angularforall
📍 Front