---
term: "Orchestration d'API"
seoTitle: "Orchestration d'API : sagas, calcul de latence, gateway vs. BFF"
headline: "Qu'est-ce que l'orchestration d'API ?"
slug: orchestration-d-api
category: backend-compute
shortDefinition: "L'orchestration d'API est un pattern où une couche de coordination appelle plusieurs API dans l'ordre et renvoie un seul résultat combiné."
relatedTerms:
  - api-gateway-architecture
  - event-driven-architecture
  - webhooks
  - microservices-vs-monolith
contrastsWith:
  - api-gateway-architecture
aboutTerms:
  - 'Orchestrator'
  - 'Saga / Compensation'
  - 'API Composition'
faq:
  - question: "Qu'est-ce que l'orchestration d'API ?"
    answer: "Coordonner plusieurs appels d'API au sein d'un même workflow piloté : une seule requête arrive, l'orchestrateur appelle chaque service backend dans le bon ordre avec les bonnes données — en gérant les dépendances, les transformations, les retries et les erreurs — et une seule réponse combinée repart. Le chef d'orchestre, dont les API sont les pupitres."
  - question: "Quelle est la différence entre orchestration et chorégraphie ?"
    answer: "L'orchestration repose sur un coordinateur central qui commande les services et suit l'état — visible, débogable, et point de couplage. La chorégraphie n'a pas de coordinateur : les services réagissent aux événements des autres — découplage maximal, mais le workflow n'existe explicitement nulle part. La règle : orchestrez quand quelqu'un doit être responsable du résultat ; chorégraphiez quand les producteurs ne se soucient réellement pas de la suite."
  - question: "Une API gateway est-elle un orchestrateur ?"
    answer: "Non — une gateway est un reverse proxy qui traite les préoccupations transverses de chaque requête : authentification, rate limits, routage. L'orchestration gère une logique de workflow en plusieurs étapes, avec un état entre les étapes. Une gateway peut agréger légèrement des réponses ; dès que l'étape deux dépend du résultat de l'étape un, vous avez quitté le territoire de la gateway."
  - question: "Quelle est la différence entre orchestration et agrégation ?"
    answer: "L'état. L'agrégation (composition d'API) lance des appels indépendants en fan-out — généralement en parallèle — puis fusionne les réponses ; aucun appel ne dépend d'un autre. L'orchestration est séquentielle et conditionnelle : l'entrée de l'étape N vient de la sortie de l'étape N−1, les échecs exigent une compensation, et le flux lui-même est de la logique."
  - question: "Quel est un exemple d'orchestration d'API ?"
    answer: "Le checkout, par excellence : valider le panier, réserver le stock, débiter la carte, créer l'expédition, envoyer la confirmation — cinq API, un ordre strict, et un échec à n'importe quelle étape doit défaire ce qui précède. La réservation de voyages et l'onboarding des utilisateurs suivent le même schéma."
  - question: "Comment gérer un échec au milieu d'un flux orchestré ?"
    answer: "Il n'existe pas de rollback entre services — une carte débitée n'est pas recréditée parce que l'expédition a échoué. Le pattern saga répond par des actions compensatoires : défaire explicitement les étapes terminées (rembourser le paiement, libérer la réservation), réessayer les échecs transitoires avec des clés d'idempotence pour qu'un débit retenté ne facture pas deux fois, et borner chaque étape par un timeout."
  - question: "Quand utiliser l'orchestration d'API ?"
    answer: "Quand un client devrait sinon enchaîner trois appels dépendants ou plus, quand les étapes exigent un ordre et une gestion d'erreurs commune, ou quand les réseaux mobiles rendent coûteux les allers-retours bavards. Évitez-la pour les appels à un seul service et les lectures purement parallèles — c'est de l'agrégation, plus simple."
  - question: "Faut-il un moteur de workflow, ou une fonction suffit-elle ?"
    answer: "Une simple fonction côté serveur suffit pour les flux courts et synchrones — quelques étapes, quelques secondes, et un échec renvoie une erreur au client. Les moteurs de workflow durables justifient leur poids quand les flux durent longtemps, doivent survivre aux redémarrages ou nécessitent des retries planifiés et des étapes d'approbation humaine."
codeLanguages: [javascript, dart, swift, kotlin]
externalAuthorities:
  - name: 'API Composition pattern — microservices.io'
    url: 'https://microservices.io/patterns/data/api-composition.html'
  - name: 'Saga pattern — microservices.io'
    url: 'https://microservices.io/patterns/data/saga.html'
  - name: 'Process Manager — Enterprise Integration Patterns'
    url: 'https://www.enterpriseintegrationpatterns.com/patterns/messaging/ProcessManager.html'
  - name: 'Backends For Frontends — Sam Newman'
    url: 'https://samnewman.io/patterns/architectural/bff/'
cta:
  title: "L'orchestrateur que vous avez déjà"
  text: "Une fonction Cloud Code de Back4app, c'est de l'orchestration légère en un seul fichier : appelez paiement, stock et expédition avec des clés conservées côté serveur, compensez en cas d'échec et renvoyez au client une seule réponse propre."
  linkText: 'Commencez gratuitement'
  linkUrl: 'https://www.back4app.com/signup'
author: 'Back4app Engineering'
publishedDate: '2026-09-16'
translationKey: api-orchestration
---

**L'orchestration d'API est un pattern où une couche de coordination appelle plusieurs API dans l'ordre et renvoie un seul résultat combiné.** La métaphore du chef d'orchestre est universelle parce qu'elle est exacte : chaque API joue sa partie, mais la *partition* — l'ordre, les dépendances, ce qui se passe quand les cuivres flanchent — appartient à l'orchestrateur. Une confusion à dissiper tout de suite : la moitié du secteur emploie « orchestration » pour désigner ce que fait sa propre catégorie de produits (gateways, plateformes d'automatisation, moteurs de workflow, routeurs GraphQL revendiquent tous le mot). Cet article désigne le pattern lui-même — et démêle les produits plus bas.

## Points clés

| Question | Réponse |
| --- | --- |
| La forme | Une requête entrante → des appels ordonnés et conditionnels → une seule réponse |
| vs. agrégation | L'agrégation lance des lectures parallèles sans état ; l'orchestration est une séquence avec état |
| vs. chorégraphie | Commandement central vs. [réaction distribuée aux événements](/glossary/fr/architecture-orientee-evenements/) |
| La vérité sur les échecs | Aucun rollback entre services n'existe — la compensation (sagas) est la réponse |
| Le levier de latence | Paralléliser tout ce que le graphe de dépendances n'interdit pas |

## Le checkout, orchestré

**JavaScript:**

```javascript
// JavaScript — Cloud Code (cloud/main.js)
// Lightweight orchestration: one function owns the checkout flow
Parse.Cloud.define('checkout', async (req) => {
  const { cartId } = req.params;

  // Independent lookups run in PARALLEL (~200 ms, not 400)
  const [cart, address] = await Promise.all([
    loadCart(cartId),
    loadAddress(req.user),
  ]);

  const reservation = await reserveInventory(cart);        // step 1
  try {
    const charge = await chargeCard(req.user, cart, {
      idempotencyKey: cartId,                              // safe to retry
    });
    const shipment = await createShipment(charge, address); // step 3
    return { orderId: shipment.orderId };                  // one response out
  } catch (e) {
    await releaseInventory(reservation); // compensate — no rollback exists
    throw e;
  }
});
```

**Flutter:**

```dart
// Flutter / Dart — Back4app Flutter SDK
// The client sees ONE call — the orchestrator owns the sequence
final result = await ParseCloudFunction('checkout')
    .execute(parameters: {'cartId': cartId});
showConfirmation(result.result['orderId']);
// Without orchestration this screen would call payment, inventory,
// and shipping itself — three round trips, and the error handling too.
```

**Swift:**

```swift
// iOS / Swift — Back4app Swift SDK
// The client sees ONE call — the orchestrator owns the sequence
let result: [String: String] = try await Cloud.run(
    name: "checkout", parameters: ["cartId": cartId])
showConfirmation(result["orderId"] ?? "")
// Without orchestration this screen would call payment, inventory,
// and shipping itself — three round trips, and the error handling too.
```

**Kotlin:**

```kotlin
// Android / Kotlin — Back4app Android SDK
// The client sees ONE call — the orchestrator owns the sequence
val params = mapOf("cartId" to cartId)
val result = ParseCloud.callFunction<Map<String, Any>>("checkout", params)
showConfirmation(result["orderId"] as String)
// Without orchestration this screen would call payment, inventory,
// and shipping itself — three round trips, and the error handling too.
```

Tout le pattern tient dans une fonction : les lectures indépendantes parallélisées, les étapes dépendantes séquencées, une clé d'idempotence qui rend l'étape dangereuse rejouable sans risque, et une compensation dans le bloc catch — parce que la réservation de stock ne s'annule pas toute seule quand la carte est refusée.

```mermaid
flowchart LR
  accTitle: Flux de checkout orchestré avec compensation en cas d'échec
  accDescr: Une seule requête client atteint l'orchestrateur, qui exécute en parallèle les lectures indépendantes, puis enchaîne les étapes dépendantes : réserver le stock, débiter la carte, créer l'expédition. Un échec après la réservation déclenche une libération compensatoire du stock avant le retour de l'erreur, puisqu'aucun rollback automatique n'existe entre services.
  C["Client<br/>un seul appel"] --> O["Orchestrateur"]
  O -->|"parallèle"| L1["Charger le panier"]
  O -->|"parallèle"| L2["Charger l'adresse"]
  L1 --> S1["1 · Réserver le stock"]
  L2 --> S1
  S1 --> S2["2 · Débiter la carte<br/>(clé d'idempotence)"]
  S2 -->|"ok"| S3["3 · Créer l'expédition"] --> R["Une seule réponse"]
  S2 -.->|"échec"| X["Compenser :<br/>libérer la réservation"] -.-> E["Erreur au client"]
```

## Gateway vs. BFF vs. agrégation vs. orchestration vs. chorégraphie

Le tableau à cinq entrées qu'aucun concurrent ne propose à lui seul :

| | Ce que c'est | État entre les étapes | Où vit la logique | Exemple |
| --- | --- | --- | --- | --- |
| [API gateway](/glossary/fr/api-gateway/) | Reverse proxy pour les préoccupations transverses | Aucun | Configuration : authentification, rate limits, routage | Un point d'entrée unique pour toutes les API |
| [BFF](/glossary/fr/api-gateway/) | Backend dédié à un client | Par requête | Remise en forme pour un frontend | BFF mobile qui allège les payloads |
| Agrégation / [composition](https://microservices.io/patterns/data/api-composition.html) | Fan-out parallèle + fusion | **Aucun — sans état** | Une jointure en mémoire | Dashboard qui lit 4 services |
| **Orchestration** | Workflow commandé en plusieurs étapes | **Oui — l'étape N alimente l'étape N+1** | La séquence et la logique d'erreur de l'orchestrateur | Checkout, onboarding |
| Chorégraphie | Services qui réagissent à des événements | Distribué, implicite | Chaque consommateur, [sans cerveau central](/glossary/fr/architecture-orientee-evenements/) | Événements de commande diffusés en fan-out |

Les deux dernières lignes forment la paire essentielle, reflétée dans l'[article sur l'EDA](/glossary/fr/architecture-orientee-evenements/) avec la même règle : **orchestrez quand quelqu'un doit être responsable du résultat d'un workflow ; chorégraphiez quand les producteurs ne se soucient réellement pas de la suite.** Les orchestrateurs parlent en *commandes* (impératives, refusables) ; la chorégraphie parle en *événements* (des faits au passé) — la même distinction, à l'échelle de l'architecture.

## Quand l'étape 3 sur 5 échoue

La section que les résultats de recherche escamotent, et la raison pour laquelle l'orchestration relève de l'ingénierie plutôt que de la plomberie. Des étapes distribuées n'ont **aucune transaction partagée** : un paiement effectué ne peut pas être annulé par une base de données qui n'en a jamais eu connaissance. Le [pattern saga](https://microservices.io/patterns/data/saga.html) est la réponse honnête — chaque étape est une action locale associée à une action *compensatoire* (débit ↔ remboursement, réservation ↔ libération), et un échec exécute les compensations de tout ce qui a déjà été fait. Trois disciplines la font fonctionner : des **clés d'idempotence** sur les étapes dangereuses, pour qu'un timeout suivi d'un retry ne débite pas deux fois (le paiement retenté avec la même clé est reconnu, pas répété) ; des **timeouts par étape**, pour qu'une dépendance bloquée ne bloque pas tout le flux ; et des **états terminaux explicites**, parce qu'un flux à moitié exécuté puis compensé est un *résultat connu* à enregistrer, pas une exception à étouffer. Le cadeau de l'orchestration, c'est que tout cela vit en un seul endroit visible — et c'est aussi son coût : cet endroit doit être mis à l'échelle, supervisé et tenu en bon état.

## Le calcul de la latence

Trois appels de 200 ms chacun : en séquence = **600 ms** ; en parallèle = **~200 ms**. La première optimisation de l'orchestrateur n'est ni le cache ni un transport astucieux — c'est une lecture honnête du graphe de dépendances : les chargements du panier et de l'adresse (indépendants) partent ensemble ; le débit (qui a besoin du panier) attend ; l'expédition (qui a besoin du débit) attend à son tour. La plupart des flux orchestrés sont une courte colonne vertébrale séquentielle d'où partent des branches parallèles, et chaque étape placée à tort sur cette colonne est de la latence visible par l'utilisateur, offerte pour rien.

## Du code ou un moteur ?

Une **simple fonction suffit** quand le flux est court et synchrone : une poignée d'étapes, quelques secondes de budget au total, et « ça a échoué » est une réponse acceptable à renvoyer à un client qui attend — ce qui décrit les besoins d'orchestration de la plupart des backends d'applications, et correspond exactement à ce qu'offre une [fonction côté serveur](/glossary/fr/cloud-code-fonctions-serverless/). Un **moteur de workflow durable** (exemples open-source : Temporal, Camunda) justifie son poids opérationnel quand les flux durent longtemps (de quelques minutes à plusieurs jours), doivent survivre à un redémarrage de processus en cours de route, ou nécessitent des retries planifiés, des étapes d'approbation humaine et un historique rejouable. La montée en gamme est réelle mais rarement urgente ; l'anti-pattern consiste à déployer un moteur pour un checkout à trois appels — ou à bricoler un état durable dans une fonction devenue un moteur sans que personne ne s'en aperçoive.

## Cas d'usage courants

- **Flux de checkout et de paiement** — la séquence dépendante type, avec de l'argent en jeu.
- **Onboarding des utilisateurs** — créer le compte, vérifier l'identité, provisionner les ressources, souhaiter la bienvenue : ordonné et compensable.
- **Assemblage d'écrans mobiles** — un appel orchestré qui remplace trois allers-retours bavards sur un [réseau à forte latence](/glossary/fr/optimisation-du-payload/).
- **Bouquets de services tiers** — vérifications KYC, devis d'expédition, enrichissement : plusieurs fournisseurs, une seule réponse, des clés conservées [côté serveur](/glossary/fr/securite-des-cles-d-api/).
- **Coutures de migration** — un orchestrateur qui masque derrière une API stable la répartition entre ancien et nouveau système pendant le [découpage d'un monolithe](/glossary/fr/microservices-vs-monolithe/).

## Devriez-vous orchestrer ? Matrice de décision

| Situation | Choix recommandé |
| --- | --- |
| 3+ appels dépendants derrière une seule action utilisateur | Orchestration — une fonction d'abord |
| Lectures parallèles indépendantes pour un seul écran | Agrégation — plus simple, sans état |
| Préoccupations transverses (authentification, limites) | La [gateway](/glossary/fr/api-gateway/) — pas de logique de workflow |
| Réactions dont les producteurs ne se soucient pas | [Événements / chorégraphie](/glossary/fr/architecture-orientee-evenements/) |
| Flux de plusieurs jours avec des étapes humaines | Un moteur de workflow durable |
| Un seul appel backend | Rien — appelez-le directement |

## Limites et trade-offs

- **L'orchestrateur attire les dépendances.** Il connaît chaque service du flux ; les changements en aval se répercutent sur lui — la visibilité et le couplage sont une seule et même propriété.
- **Il est sur le chemin critique.** Chaque flux le traverse, donc sa latence, sa scalabilité et son budget de disponibilité relèvent du produit, pas d'une note de bas de page sur l'infrastructure.
- **La compensation n'est pas une annulation.** Un remboursement est un nouvel événement avec ses propres modes de défaillance, pas une machine à remonter le temps ; les sagas échangent l'atomicité contre l'explicite, et cet explicite doit être géré.
- **La logique métier migre vers l'orchestrateur.** Sans gouvernance, il absorbe des décisions qui reviennent aux services propriétaires des données — la séquence ici, la sémantique là-bas.
- **L'orchestration synchrone hérite des limites du synchrone.** Un client qui patiente pendant cinq étapes reste bloqué à attendre ; les flux qui débordent de la fenêtre de la requête relèvent de [jobs](/glossary/fr/jobs-en-arriere-plan/) avec un statut, pas de timeouts plus longs.

## L'orchestration sur Back4app

Back4app est une plateforme open-source de Backend as a Service (BaaS) qui combine une base de données gérée, des API REST et GraphQL générées automatiquement, l'authentification, le stockage de fichiers et des fonctions serverless avec Cloud Code. L'orchestration légère est ce qu'une [fonction Cloud Code](/glossary/fr/cloud-code-fonctions-serverless/) fait naturellement, et les onglets de code montrent le pattern complet : une fonction `checkout` qui parallélise les lectures indépendantes, séquence les étapes dépendantes, conserve les clés des services tiers [côté serveur](/glossary/fr/securite-des-cles-d-api/), compense dans le bloc catch et renvoie une seule réponse à un client mobile qui n'a fait qu'un seul appel. La fonction s'exécute à côté de la base de données (l'état de la commande et les résultats terminaux ne sont qu'à une écriture de distance), le contexte d'authentification arrive dans `request.user`, et il n'y a aucune couche d'orchestration distincte à déployer ou à mettre à l'échelle. Le jour où un flux dépassera la fenêtre de la requête — approbations, attentes d'une journée — ce sera le moment de passer à un moteur de workflow ; d'ici là, l'orchestrateur est un fichier dans votre dépôt.