Qu'est-ce que l'architecture composable ? Le guide MACH et API-first

L'architecture composable consiste à construire un système logiciel avec des composants indépendants, interchangeables et intégrés par API, plutôt qu'avec une seule plateforme tout-en-un. Elle englobe le mouvement headless et s'aligne souvent avec les principes promus par la MACH Alliance, qui défend les technologies d'entreprise ouvertes et composables.

Essayez Apidog aujourd'hui

Une clarification rapide avant de commencer

Le mot « composable » est utilisé dans plusieurs contextes. Ici, on parle uniquement d'architecture logicielle.

• Architecture composable : vous assemblez une application à partir de capacités métier indépendantes, intégrées via des API.
• Infrastructure composable : concept d'infrastructure où calcul, stockage et réseau sont mutualisés puis alloués à la demande.
• Composabilité DeFi : logique blockchain où des smart contracts s'empilent comme des « legos de l'argent ».

Dans cet article, « composable » signifie donc : architecture applicative modulaire, orientée API et centrée sur les capacités métier.

Ce que signifie réellement l'architecture composable

Un système composable est construit avec des unités autonomes qui couvrent chacune une fonction métier complète. Chaque unité expose une API, possède sa logique, ses données et peut être remplacée sans reconstruire toute l'application.

Cette unité s'appelle une capacité métier packagée, ou PBC (Packaged Business Capability). Gartner définit les PBC comme des capacités déployables indépendamment, contenant données, logique et processus métier, et interagissant avec les autres applications via des API et des événements.

Exemples de PBC :

• paiement : méthodes de paiement, fraude, remboursements, litiges ;
• recherche : indexation, ranking, traitement des requêtes ;
• inventaire : disponibilité produit, stocks, réservations ;
• identité : authentification, profils, rôles, permissions.

Une PBC n'expose pas une table SQL brute. Elle expose une API métier stable, par exemple :

GET /payments/{paymentId}
POST /payments
POST /payments/{paymentId}/refunds

L'objectif est simple : composer votre produit à partir de blocs métier remplaçables.

Composabilité vs monolithe

Un monolithe regroupe toutes les capacités dans une seule application déployable, souvent avec une base de données partagée. C'est simple au départ, mais plus difficile à faire évoluer lorsque les domaines métier divergent.

L'architecture composable sépare ces capacités. Si vous connaissez déjà la différence entre monolithe et microservices, la composabilité ajoute une lecture métier : les microservices sont une décomposition technique, les PBC sont une décomposition par capacité métier.

Dimension	Monolithe	Architecture composable
Unité de changement	Toute l'application	Une PBC
Données	Base de données partagée	Données possédées par chaque capacité
Choix fournisseur	Suite unique	Meilleur outil par capacité
Front-end	Couplé au back-end	Découplé, multi-canal
Intégration	Appels internes	API et événements
Risque de dépendance	Élevé	Plus faible si les contrats sont maîtrisés

Le compromis : vous gagnez en flexibilité, mais vous devez gérer plus de contrats, d'intégrations, de tests et d'observabilité.

MACH : le modèle le plus courant

Quand une équipe parle d'architecture composable, elle fait souvent référence aux principes MACH.

MACH signifie :

• M — Microservices : les capacités sont déployables indépendamment.
• A — API-first : chaque capacité expose une API explicite.
• C — Cloud-native : les composants sont conçus pour l'élasticité et les services cloud.
• H — Headless : le front-end est séparé du back-end.

Ces termes ne sont pas synonymes :

• Headless est une séparation front/back.
• MACH est une approche structurée pour construire des systèmes composables.
• Composable est le concept plus large.

En pratique, une architecture composable ressemble souvent à ceci :

[Web App]       [Mobile App]       [Kiosk]
    |               |                |
    +---------------+----------------+
                    |
              [API Gateway]
                    |
    +---------------+----------------+----------------+
    |               |                |                |
[PBC Search]   [PBC Payment]   [PBC Inventory]   [PBC Identity]
    |               |                |                |
[Search DB]    [Payment DB]    [Stock DB]        [User DB]

Chaque PBC évolue indépendamment, mais les API doivent rester cohérentes.

La colonne vertébrale : API-first

Dans une architecture composable, l'API est le contrat entre les composants. Si ce contrat casse, l'intégration casse.

C'est pourquoi le développement API-first devient central.

Dans un monolithe, deux modules peuvent partager une base de données ou s'appeler directement. Dans un système composable, ce raccourci disparaît. Une capacité doit être consommable uniquement via son API.

Exemple de contrat minimal pour une PBC inventaire :

openapi: 3.0.3
info:
  title: Inventory API
  version: 1.0.0
paths:
  /products/{productId}/availability:
    get:
      summary: Vérifier la disponibilité d'un produit
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Disponibilité du produit
          content:
            application/json:
              schema:
                type: object
                properties:
                  productId:
                    type: string
                  available:
                    type: boolean
                  quantity:
                    type: integer

Cette API devient un produit interne. Vos front-ends, partenaires, jobs batch et autres PBC la consomment directement. C'est exactement pourquoi l'API est le produit dans une architecture composable.

Comment découper une architecture en PBC

Pour rendre l'approche concrète, commencez par identifier les domaines métier stables.

1. Listez les capacités métier

Exemple pour une plateforme e-commerce :

• catalogue ;
• recherche ;
• panier ;
• paiement ;
• commandes ;
• inventaire ;
• livraison ;
• identité client ;
• notifications.

2. Définissez les frontières de données

Chaque PBC doit posséder ses données. Évitez ce type de dépendance :

Payment Service ---> lit directement dans la table orders

Préférez :

Payment Service ---> appelle Orders API

ou :

Orders Service ---> publie OrderCreated
Payment Service ---> consomme OrderCreated

3. Choisissez le mode d'intégration

Utilisez des API synchrones quand le consommateur a besoin d'une réponse immédiate :

GET /orders/{orderId}

Utilisez des événements pour propager des changements d'état :

{
  "event": "OrderCreated",
  "orderId": "ord_123",
  "customerId": "cus_456",
  "total": 129.99
}

4. Versionnez les contrats

Une PBC remplaçable doit avoir une API stable. Évitez les changements cassants non versionnés.

Exemple :

GET /v1/products/{id}
GET /v2/products/{id}

Ou utilisez une stratégie de compatibilité ascendante :

• ajouter des champs sans supprimer les anciens ;
• rendre les nouveaux champs optionnels ;
• documenter les dépréciations ;
• tester les contrats en CI.

Avantages et compromis

Les avantages principaux :

• Meilleur outil par capacité : vous choisissez le bon moteur de recherche, le bon CMS, le bon service de paiement, etc.
• Changements indépendants : une PBC peut évoluer sans redéployer tout le système.
• Moins de dépendance fournisseur : les composants sont plus facilement remplaçables.
• Livraison parallèle : plusieurs équipes peuvent travailler sur des capacités distinctes.
• Multi-canal : web, mobile, bornes, applications partenaires et autres clients consomment les mêmes API.

Les coûts réels :

• Plus d'intégration : chaque capacité ajoute des contrats à maintenir.
• Plus de discipline API : un changement cassant peut impacter plusieurs équipes.
• Plus d'observabilité : logs, traces, métriques et erreurs sont distribués.
• Plus de gouvernance : sécurité, authentification, autorisation et versioning doivent être cohérents.
• Plus de conception en amont : les frontières métier doivent être réfléchies avant de coder.

La composabilité est pertinente si vous avez besoin de flexibilité, d'évolutivité et de plusieurs canaux. Elle est excessive si un monolithe clair et bien structuré suffit.

Où Apidog s'intègre : le pilier API-first

Apidog ne transforme pas automatiquement votre système en architecture composable. Ce n'est pas un CMS, un moteur de commerce, une passerelle API ou une plateforme MACH.

Son rôle est plus ciblé : gérer le pilier API-first, c'est-à-dire la couche contractuelle dont dépend tout système composable.

Avec Apidog, vous pouvez :

• concevoir vos contrats API avant l'implémentation ;
• générer une documentation exploitable par les consommateurs ;
• créer des mock servers pour débloquer les front-ends ;
• tester les endpoints ;
• exécuter les tests API en CI ;
• piloter certains workflows depuis vos outils via MCP.

Workflow typique :

1. Définir le contrat OpenAPI
2. Générer un mock server
3. Développer le front-end contre le mock
4. Implémenter la PBC réelle
5. Lancer les tests API en CI
6. Publier la documentation

Dans une architecture où l'API est le produit, cette discipline évite que les PBC deviennent des boîtes noires impossibles à intégrer.

Vous pouvez télécharger Apidog pour concevoir et simuler un contrat avant même que le back-end existe.

Quand adopter l'architecture composable

Adoptez la composabilité si plusieurs de ces conditions sont vraies :

• vous devez servir plusieurs canaux : web, mobile, magasin, vocal, partenaires ;
• vos capacités métier évoluent à des rythmes différents ;
• vous voulez remplacer certains fournisseurs sans reconstruire toute la plateforme ;
• le verrouillage fournisseur est un risque commercial ;
• vous avez plusieurs équipes travaillant en parallèle ;
• vous pouvez maintenir des contrats API propres sur la durée ;
• vous avez besoin d'observabilité et de scalabilité par domaine métier.

Gardez un monolithe si :

• l'équipe est petite ;
• le produit est encore en validation ;
• les domaines métier changent constamment ;
• vous n'avez pas encore de besoin multi-canal ;
• la complexité opérationnelle coûterait plus cher que la flexibilité gagnée.

Une bonne règle pratique :

Commencez simple.
Découpez quand une capacité a une vraie raison métier d'évoluer seule.

Checklist d'implémentation

Avant de migrer vers une architecture composable, vérifiez ces points :

• [ ] Les domaines métier sont identifiés.
• [ ] Chaque PBC a un propriétaire clair.
• [ ] Chaque PBC possède ses données.
• [ ] Les contrats API sont documentés.
• [ ] Les changements cassants sont versionnés.
• [ ] Les mocks sont disponibles pour les consommateurs.
• [ ] Les tests API sont automatisés.
• [ ] L'authentification est cohérente entre services.
• [ ] Les logs, métriques et traces sont centralisés.
• [ ] Les dépendances fournisseur sont documentées.
• [ ] Les événements métier sont nommés et versionnés.
• [ ] Les front-ends ne dépendent pas d'implémentations internes.

Questions fréquemment posées

L'architecture composable est-elle la même chose que les microservices ?

Non, mais les deux se recoupent. Les microservices sont une façon technique de découper un système en services déployables indépendamment. L'architecture composable découpe le système selon des capacités métier et insiste sur leur interchangeabilité via API.

Les microservices sont souvent une manière d'implémenter le back-end d'un système composable. Pour une comparaison plus large, consultez monolithe versus microservices.

Quelle est la différence entre composable et headless ?

Headless signifie que le front-end est séparé du back-end. Plusieurs interfaces peuvent consommer les mêmes API.

Composable est plus large : le système entier est assemblé à partir de capacités indépendantes connectées par API. Headless est donc un principe fréquent dans les architectures composables, mais il ne suffit pas à lui seul.

Qu'est-ce qu'une capacité métier packagée ?

Une PBC est une unité autonome qui gère une fonction métier complète, avec ses données, sa logique, ses processus et ses API.

Exemples :

• recherche ;
• paiement ;
• inventaire ;
• identité ;
• notifications.

Chaque PBC doit être compréhensible, testable et remplaçable par son contrat API.

Ai-je besoin d'une plateforme API pour adopter l'architecture composable ?

Vous avez besoin d'une méthode fiable pour concevoir, tester, simuler, documenter et versionner vos API. Cela peut être un ensemble d'outils ou une plateforme unique.

L'important n'est pas seulement l'outil, mais la discipline :

• contrats clairs ;
• mocks disponibles ;
• documentation à jour ;
• tests automatisés ;
• versioning maîtrisé.

En résumé

L'architecture composable consiste à assembler un système avec des capacités métier indépendantes, connectées par API. Headless, MACH et microservices sont des approches ou principes liés, mais le point central reste le même : le contrat API est la couche qui tient l'ensemble.

Si vos contrats sont instables, votre architecture composable devient fragile. Si vos contrats sont bien conçus, testés, simulés et documentés avec un outil comme Apidog, vous obtenez une base solide pour construire un système remplaçable, multi-canal et moins dépendant d'une seule plateforme.