API Headless Commerce : Définition, MACH, Commerce Composable et couche contractuelle

Si vous avez déjà acheté sur une vitrine personnalisée qui ne ressemblait pas à un thème standard, une API de commerce headless travaillait probablement en coulisses. Une API de commerce headless est le contrat exposé par un backend de commerce pour permettre à une vitrine web, mobile ou partenaire de lire des produits, créer des paniers et passer des commandes sans dépendre d’un frontend intégré. Cet article explique comment l’implémenter, comment cela se relie au commerce composable et MACH, et pourquoi votre API devient le point de coordination principal entre les équipes. Il prolonge l’idée que les logiciels deviennent headless et votre API est désormais le produit.

Essayez Apidog aujourd’hui

Ce que « headless » signifie dans le commerce

Dans une plateforme de commerce traditionnelle, le catalogue, le panier, le paiement et les pages HTML vivent dans le même système. Vous configurez un thème, vous adaptez quelques modèles, puis vous déployez.

En commerce headless, vous séparez ces responsabilités :

• Backend commerce : catalogue, prix, inventaire, panier, commandes, clients.
• Frontend : vitrine web, application mobile, borne, assistant vocal ou autre canal.
• API : contrat qui relie les deux.

La « tête » correspond à la couche de présentation. Devenir headless signifie retirer cette tête fixe et exposer la logique commerciale via une API.

Exemple de flux minimal côté vitrine :

sequenceDiagram
  participant UI as Vitrine React / Mobile
  participant API as API commerce
  participant BE as Backend commerce

  UI->>API: GET /products/sku-123
  API->>BE: Lire produit, prix, stock
  BE-->>API: Données produit
  API-->>UI: JSON produit

  UI->>API: POST /carts
  API->>BE: Créer panier
  BE-->>API: Panier créé
  API-->>UI: cartId

Le bénéfice principal est le découplage. L’équipe frontend choisit son framework et son cycle de livraison. L’équipe backend maintient les règles métier. L’API devient la frontière technique entre les deux.

Le coût est réel : contrairement à une plateforme traditionnelle, vous devez construire, héberger et maintenir votre vitrine. Le headless est pertinent quand un thème standard ne suffit plus, ou quand plusieurs canaux doivent consommer le même backend.

Headless vs composable vs MACH

Ces termes sont proches, mais ils ne couvrent pas la même portée.

Terme	Ce qu'il décrit	Portée
Commerce headless	Frontend découplé d'un unique backend de commerce, connecté par une API	Un backend, un ou plusieurs frontends
Commerce composable	L'ensemble de la pile est décomposé en services interchangeables "best-of-breed" : catalogue, recherche, paiements, PIM, OMS	De nombreux services indépendants assemblés ensemble
MACH	Un ensemble de principes architecturaux que les piles composables ont tendance à suivre	Une philosophie, pas un produit

Le headless est le cas le plus restreint. Vous pouvez être headless avec un backend monolithique unique si la vitrine communique avec lui via une API.

Le commerce composable va plus loin. Vous assemblez plusieurs services indépendants : moteur de recherche, paiement, PIM, OMS, CMS, service de promotions, etc. Chaque composant expose sa propre API.

MACH désigne les principes utilisés dans beaucoup de piles composables. Selon la MACH Alliance, créée en 2020, MACH signifie :

• Microservices
• API-first
• Cloud-native SaaS
• Headless

Le point critique est API-first. Dans une architecture MACH, l’API n’est pas un ajout secondaire : c’est le mécanisme principal de communication entre services, ce qui rejoint l’approche consistant à traiter votre API comme un produit.

Ce qu'une API de commerce headless expose réellement

Une API de commerce headless couvre généralement ces domaines :

• Catalogue et produits : produits, variantes, collections, médias.
• Recherche et navigation : requêtes, filtres, tri, facettes.
• Panier et paiement : création de panier, ajout/suppression d’articles, promotions, checkout.
• Clients : connexion, profil, adresses, historique de commandes.
• Inventaire et prix : disponibilité, prix selon contexte, devise ou segment client.

Certaines plateformes séparent ces fonctions en deux API :

• API vitrine : orientée lecture et interactions client.
• API administration : back-office, catalogue, commandes, configuration.

Exemple REST minimal

GET /products/sku-123 HTTP/1.1
Host: api.example.com
Accept: application/json

Réponse possible :

{
  "id": "prod_123",
  "sku": "sku-123",
  "name": "T-shirt coton",
  "price": {
    "amount": 2990,
    "currency": "EUR"
  },
  "inventory": {
    "available": true,
    "quantity": 42
  }
}

Ajout au panier :

POST /carts/cart_456/items HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "sku": "sku-123",
  "quantity": 2
}

Exemple GraphQL minimal

GraphQL est courant dans le commerce headless parce qu’une vitrine peut demander uniquement les champs nécessaires :

query ProductPage($sku: String!) {
  product(sku: $sku) {
    id
    name
    description
    variants {
      sku
      price {
        amount
        currency
      }
      inventory {
        available
      }
    }
  }
}

REST reste tout à fait valide. Certaines plateformes proposent les deux. Le choix du protocole dépend de vos besoins, mais la stabilité du contrat est plus importante que le style d’API. Pour comparer les deux approches, consultez REST vs GraphQL.

Les principales plateformes

L’écosystème headless se divise globalement entre moteurs SaaS et moteurs open source. Voici les noms que vous croiserez souvent :

• commercetools : membre fondateur de la MACH Alliance et plateforme de commerce composable souvent citée. API-first et cloud-native par conception.
• Shopify : prend en charge les approches headless via son API Storefront, avec Hydrogen comme framework React pour la consommer. Si vous êtes déjà dans l’écosystème Shopify, ce tutoriel API Shopify est un bon point de départ.
• BigCommerce : prend en charge le headless avec ses API GraphQL Storefront et Checkout en plus de son catalogue. Consultez ce guide sur l’utilisation des API BigCommerce.
• Saleor : moteur open source, GraphQL-first, construit sur Python et Django.
• Medusa : moteur open source construit sur Node.js et TypeScript, populaire auprès des équipes JavaScript qui veulent contrôler le backend.

Avant de choisir, vérifiez toujours :

• le modèle tarifaire ;
• les limites d’API ;
• les options d’hébergement ;
• la couverture fonctionnelle des API ;
• la qualité de la documentation ;
• les mécanismes d’authentification ;
• les possibilités de versioning.

Le modèle reste le même : le moteur expose la logique commerciale via une API, et vous construisez la tête.

Pourquoi les équipes dépendent du contrat d'API de commerce

Une fois la vitrine découplée, l’API n’est plus une simple couche technique. Elle devient l’accord commun entre toutes les équipes.

L’équipe frontend ne peut pas livrer une page produit sans connaître la forme exacte d’une réponse produit. L’équipe mobile consomme souvent le même contrat. Les intégrations partenaires, les services de fidélité, les services fiscaux ou les flux marketplace dépendent aussi de ces endpoints.

Si une réponse change sans avertissement, plusieurs consommateurs peuvent casser en même temps.

Exemple de changement dangereux :

{
  "id": "prod_123",
- "price": 2990
+ "price": {
+   "amount": 2990,
+   "currency": "EUR"
+ }
}

Ce changement est logique côté backend, mais il est incompatible pour tout client qui attendait price comme nombre.

Une API de commerce headless doit donc être gérée comme un produit :

• contrat documenté ;
• exemples de requêtes et réponses ;
• versioning explicite ;
• changements additifs quand c’est possible ;
• fenêtres de dépréciation ;
• tests automatisés ;
• validation en CI.

Les tests de contrat permettent de détecter les ruptures avant qu’elles n’arrivent en production ou dans l’intégration d’un partenaire.

Implémenter une API headless avec une approche design-first

Une approche pratique consiste à commencer par le contrat, pas par le code.

1. Définir les ressources principales

Commencez par lister les ressources nécessaires à la vitrine :

Product
Variant
Price
Inventory
Cart
CartItem
Customer
Order
Promotion

Ensuite, mappez les parcours utilisateur :

Voir une page produit
Rechercher un produit
Créer un panier
Ajouter un article
Appliquer un code promo
Passer au paiement
Voir l’historique de commandes

2. Décrire les endpoints ou les opérations GraphQL

Exemple REST :

paths:
  /products/{sku}:
    get:
      summary: Lire un produit par SKU
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Produit trouvé
        "404":
          description: Produit introuvable

Exemple GraphQL :

type Query {
  product(sku: String!): Product
  searchProducts(query: String!, limit: Int = 20): ProductSearchResult!
}

type Mutation {
  createCart: Cart!
  addCartItem(cartId: ID!, sku: String!, quantity: Int!): Cart!
}

3. Ajouter des exemples réalistes

Une API de commerce est difficile à consommer si elle ne fournit pas d’exemples concrets. Ajoutez au minimum :

• un produit simple ;
• un produit avec variantes ;
• un produit en rupture de stock ;
• un panier vide ;
• un panier avec promotion ;
• une erreur de validation ;
• une erreur d’authentification.

Exemple d’erreur utile :

{
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "La quantité demandée n'est pas disponible.",
    "details": {
      "sku": "sku-123",
      "requestedQuantity": 5,
      "availableQuantity": 2
    }
  }
}

4. Simuler l’API avant le backend

Une simulation permet à l’équipe frontend d’avancer sans attendre que toute la logique backend soit terminée.

Flux recommandé :

Contrat OpenAPI / GraphQL
        ↓
Serveur de simulation
        ↓
Développement frontend
        ↓
Tests de contrat
        ↓
Backend réel

C’est l’un des principaux avantages d’une architecture headless : les équipes peuvent travailler en parallèle si le contrat est clair.

Où Apidog s'intègre

Apidog ne gère pas votre boutique. Ce n’est ni un moteur de commerce, ni un CMS, ni une passerelle de paiement. Il ne rend pas votre pile headless ou composable à lui seul.

Son rôle est de gérer la couche API-first : concevoir, tester, simuler et documenter le contrat dont votre vitrine et vos intégrations dépendent.

Dans un projet de commerce headless, vous pouvez l’utiliser pour :

• Concevoir le contrat en premier : modélisez l’API vitrine ou administration comme une spécification OpenAPI dans Apidog avant que le code backend soit finalisé.
• Simuler l’API : générez un serveur de simulation à partir de la spécification pour permettre au frontend de travailler avec des réponses produits et paniers réalistes. Voir cette explication sur les API de simulation.
• Tester le contrat en CI : exécutez les tests d’API sans interface graphique avec la CLI Apidog dans un pipeline.
• Documenter l’API : publiez une documentation interactive pour les équipes frontend, mobile et partenaires.

Pour approfondir l’impact d’une API lorsqu’elle devient l’interface principale du produit, lisez les logiciels deviennent headless et votre API est désormais le produit. Pour tester le flux, téléchargez Apidog et importez une spécification existante.

Checklist d’implémentation

Avant de lancer une vitrine headless, vérifiez ces points :

• [ ] Les ressources principales sont définies.
• [ ] Les endpoints ou opérations GraphQL sont documentés.
• [ ] Les erreurs ont une structure cohérente.
• [ ] Les exemples couvrent les cas réels : stock, promotions, variantes, erreurs.
• [ ] La stratégie d’authentification est claire.
• [ ] Le versioning est défini.
• [ ] Les changements incompatibles sont détectés par des tests.
• [ ] Une simulation est disponible pour le frontend.
• [ ] La documentation est accessible aux équipes internes et partenaires.
• [ ] Les contrats sont testés dans la CI.

Questions fréquemment posées

Le commerce headless est-il la même chose que le commerce composable ?

Non. Le commerce headless découple la vitrine d’un backend de commerce unique via une API. Le commerce composable assemble plusieurs services indépendants "best-of-breed", chacun avec sa propre API, en une seule expérience. Une pile composable est généralement headless, mais une configuration headless avec un backend monolithique unique n’est pas nécessairement composable.

Ai-je besoin de GraphQL pour une API de commerce headless ?

Non. GraphQL est courant parce qu’il permet à la vitrine de demander exactement les champs nécessaires en un seul appel. C’est utile pour les pages produit, les listes et les paniers. Mais beaucoup d’API de commerce headless utilisent REST, et certaines plateformes proposent les deux. Le protocole importe moins que la stabilité, la documentation et la testabilité du contrat.

Puis-je tester une API de commerce headless avant que le backend ne soit construit ?

Oui. C’est l’un des principaux intérêts d’une approche design-first. Si vous modélisez le contrat d’API comme une spécification, vous pouvez générer un serveur de simulation qui renvoie des réponses réalistes. La vitrine peut être développée contre cette simulation, puis basculer vers les endpoints réels plus tard.

Qu'est-ce que la MACH Alliance ?

La MACH Alliance est un groupe industriel créé en 2020 pour promouvoir des piles technologiques ouvertes et "best-of-breed" construites sur les principes des Microservices, de l’API-first, du SaaS natif du cloud et du Headless. Des fournisseurs comme commercetools sont des membres fondateurs. MACH est un ensemble de principes architecturaux, pas un produit unique.

Le contrat est le magasin

Le commerce headless déplace la valeur du thème vers l’API. Une fois la vitrine découplée, l’API de commerce devient ce sur quoi vos équipes frontend, mobile et partenaires construisent réellement.

Le commerce composable et MACH poussent cette logique plus loin en faisant de l’API-first un principe d’architecture, pas un simple détail d’intégration.

Apidog n’est pas le moteur de commerce sous-jacent, mais il peut fournir l’espace où concevoir, simuler, tester et documenter le contrat. Si votre projet headless dépend d’une API stable, Apidog vous aide à traiter ce contrat comme une partie centrale du produit.