Qu'est-ce que l'orchestration d'API ?

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

Le checkout, orchestré

// 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 — 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.

// 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.

// 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.

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

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

Les deux dernières lignes forment la paire essentielle, reflétée dans l’article sur l’EDA 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 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. 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.
• 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.
• 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.

Devriez-vous orchestrer ? Matrice de décision

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 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 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, 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.