Carte Context Mapping #1 : Open-host Service

📇 Carte #1 : Open-host Service

Vue Rapide

🎯 Objectif : Un contexte expose une interface commune à plusieurs clients

👥 Relation d’équipe : Upstream/Downstream (asymétrique)

📊 Couplage : Moyen → Bas (dépend de la stabilité de l’interface)

Concept

L’équipe upstream expose une interface (API, événements, etc.) ouverte et publique que tous les clients downstream peuvent utiliser.

L’interface évolue pour accommoder de nouveaux besoins mais reste cohérente et documentée.

Upstream (Open-host Service)
        ↓ (API publique stable)
    Downstream 1
    Downstream 2
    Downstream 3 (clients multiples)

Quand l’Utiliser ? ✅

  • ✅ Plusieurs clients downstream avec des besoins similaires
  • ✅ L’upstream peut réussir indépendamment des clients
  • ✅ Vous avez une équipe dédiée pour maintenir l’interface
  • ✅ Les besoins des clients sont génériques et prévisibles
  • ✅ Vous voulez une approche scalable (ajouter de nouveaux clients facilement)

Exemples

  • Stripe API : Interface publique pour les paiements
  • Système de catalogue : Expose une API de consultation
  • Service d’authentification : Interface standardisée pour login

Quand l’Éviter ? ❌

  • ❌ Besoin très spécifique d’un seul client
  • ❌ L’interface change constamment (domaine trop exploratoire)
  • ❌ Les besoins des clients sont radicalement différents
  • ❌ Pas de ressource pour maintenir l’interface

Questions Clés à se Poser 💭

  1. Y a-t-il plusieurs clients qui consomment ce service ?
  2. L’interface peut-elle être stable et générique ?
  3. L’upstream peut-il investir dans la maintenance de l’interface ?
  4. Les clients acceptent-ils de se conformer à l’interface publique ?
  5. Comment versionnez-vous l’API pour ne pas casser les clients ?

Implications pour l’Équipe Upstream

Responsabilités

  • ✓ Concevoir une interface générique et réutilisable
  • ✓ Documenter l’interface publique clairement
  • ✓ Maintenir la compatibilité (versioning, backward compatibility)
  • ✓ Supporter les clients : comprendre leurs besoins
  • ✓ Évoluer l’interface pour accueillir de nouveaux cas

Avantages

  • ✓ Scale facilement : ajouter de nouveaux clients sans recoder
  • ✓ Faible coupling : les clients n’impactent pas la logique upstream
  • ✓ Autonomie des clients : ils peuvent évoluer indépendamment

Risques

  • ⚠️ L’interface devient un goulot d’étranglement
  • ⚠️ Les besoins des clients créent une interface trop générique ou trop complexe
  • ⚠️ Maintenance : gérer plusieurs versions de l’API
  • ⚠️ Les clients sont limités à ce que l’interface propose

Implications pour l’Équipe Downstream

Responsabilités

  • ✓ Utiliser l’interface telle qu’elle est (pas de négociation)
  • ✓ Adapter votre domaine à l’interface upstream
  • ✓ Respecter les contrats (versioning, breaking changes)

Avantages

  • ✓ Simple d’intégration : pas de traduction complexe
  • ✓ Fiabilité : interface bien documentée et stable
  • ✓ Pas de dépendance forte : vous pouvez changer sans affecter l’upstream

Risques

  • ⚠️ L’interface ne vous convient pas parfaitement
  • ⚠️ Adapter votre logique à l’interface plutôt que l’inverse
  • ⚠️ Si l’API change, vous devez vous adapter rapidement

Exemple Concret : Système de Paiement

Contexte Upstream : Payment Service

Interface publique (API REST) :
- POST /payments → créer un paiement
- GET /payments/{id} → récupérer le statut
- POST /refunds → effectuer un remboursement
- Events : PaymentCreated, PaymentSucceeded, PaymentFailed

Contextes Downstream

  • Order Service : Utilise l’API de paiement
  • Subscription Service : Utilise l’API de paiement
  • Invoicing Service : Reçoit les événements PaymentSucceeded

Décisions

  • ✅ Une seule interface pour tous les cas
  • ✅ Versionning : /v1/payments, /v2/payments si breaking change
  • ✅ Documentation : Swagger/OpenAPI pour chaque version

Intégration avec Context Mapping

Relations d’Équipe

Payment Team (Upstream - Open-host Service)
        ↓ (API publique)
    Order Team (Downstream - Conformist)
    Subscription Team (Downstream - Conformist)
    Invoicing Team (Downstream - Conformist)

Patterns Downstream Associés

  • Conformist : Les clients adoptent l’interface telle qu’elle
  • Anticorruption Layer : Un client crée une couche de traduction (optionnel)

Checklist de Mise en Place ✓

  • Vous avez identifié plusieurs clients potentiels
  • L’interface est générique et peut servir plusieurs cas
  • Vous avez une équipe dédiée pour la maintenir
  • L’interface est documentée (Swagger, wiki, etc.)
  • Vous avez une stratégie de versioning claire
  • Les clients savent à quoi s’attendre

Ressources et Lectures

Notes de Facilitation pour l’Atelier

Animation

  • Demandez : “Combien de clients potentiels avez-vous ?”
  • Explorez : “L’interface peut-elle rester stable ?”
  • Validez : “Quelqu’un d’autre que vous peut-il la comprendre et l’utiliser ?”

Pièges Communs

  • ⚠️ Penser que tout est OpenAPI → certains domaines n’y sont pas adaptés
  • ⚠️ Négliger la maintenance → les interfaces dégénèrent
  • ⚠️ Trop générique → personne ne la comprend

Questions Provocatrices

  • “Et si vous aviez 10 clients ? 100 clients ?”
  • “Comment réagiriez-vous si un client dit ‘Votre API ne me convient pas’ ?”