Skip to content
Learni
View all tutorials
Architecture Backend

Comment maîtriser AsyncAPI pour APIs événementielles en 2026

22 minEXPERT
TypeScriptEvent-DrivenAsyncAPI

Introduction

AsyncAPI est le standard ouvert pour documenter les APIs asynchrones et orientées événements. Contrairement à OpenAPI qui cible les APIs REST synchrones, AsyncAPI modélise les flux de messages entre producteurs et consommateurs. En 2026, son adoption est essentielle pour les architectures microservices, IoT et data streaming. Ce tutoriel expert vous guide de la rédaction d'une spécification complète à la génération et l'implémentation de code fonctionnel en TypeScript avec Kafka. Vous apprendrez à gérer les schémas, bindings et security schemes de manière professionnelle.

Prérequis

  • Node.js 20+ et TypeScript 5.4+
  • Connaissances avancées des architectures événementielles
  • Docker pour Kafka et l'AsyncAPI Generator
  • npm ou pnpm installé

Spécification AsyncAPI de base

asyncapi.yaml
asyncapi: '3.0.0'
info:
  title: Order Processing API
  version: '1.0.0'
  description: API événementielle pour le traitement des commandes
servers:
  production:
    host: kafka.cluster.local:9092
    protocol: kafka
channels:
  orders.created:
    address: orders/created
    messages:
      orderCreated:
        payload:
          type: object
          properties:
            orderId:
              type: string
            amount:
              type: number

Ce fichier YAML définit le document AsyncAPI 3.0 minimal avec un serveur Kafka et un canal pour les événements de création de commande. Il inclut le schéma du payload pour garantir la validation automatique.

Ajout d'opérations et bindings

asyncapi.yaml
operations:
  sendOrderCreated:
    action: send
    channel: $ref: '#/channels/orders.created'
    messages:
      - $ref: '#/channels/orders.created/messages/orderCreated'
    bindings:
      kafka:
        key:
          type: string
        partition: 0
  receiveOrderCreated:
    action: receive
    channel: $ref: '#/channels/orders.created'
    messages:
      - $ref: '#/channels/orders.created/messages/orderCreated'

Les opérations définissent explicitement le rôle send/receive et les bindings Kafka spécifiques. Cela permet aux générateurs de code de produire des stubs correctement typés et configurés.

Génération du code TypeScript

terminal
npx @asyncapi/generator@2.5.0 asyncapi.yaml @asyncapi/nodejs-template -o ./generated -p server=production

La commande génère un SDK TypeScript complet incluant les types, le publisher et le subscriber avec les bindings Kafka. Le dossier generated contient du code prêt à l'emploi et compilable.

Implémentation du Publisher

src/publisher.ts
import { OrderCreatedProducer } from '../generated';

const producer = new OrderCreatedProducer({
  clientId: 'order-service',
  brokers: ['kafka.cluster.local:9092']
});

export async function publishOrderCreated(order: { orderId: string; amount: number }) {
  await producer.send({
    key: order.orderId,
    value: order,
    partition: 0
  });
}

Le publisher utilise les classes générées pour publier des messages avec typage strict. Cela évite les erreurs de schéma et assure la compatibilité avec les consommateurs.

Implémentation du Subscriber

src/subscriber.ts
import { OrderCreatedConsumer } from '../generated';

const consumer = new OrderCreatedConsumer({
  groupId: 'order-processor',
  clientId: 'processor-service',
  brokers: ['kafka.cluster.local:9092']
});

consumer.on('orderCreated', async (message) => {
  console.log(`Processing order ${message.orderId}`);
  // Logique métier ici
});

Le subscriber s'abonne automatiquement au canal et reçoit les messages typés. La gestion des erreurs et le commit des offsets sont inclus dans le template généré.

Bonnes pratiques

  • Versionnez toujours vos documents AsyncAPI avec des numéros sémantiques
  • Utilisez des schémas JSON Schema stricts et réutilisables
  • Déclarez explicitement les security schemes (OAuth, API keys)
  • Testez la compatibilité des messages avec AsyncAPI Validator
  • Intégrez la génération de code dans votre pipeline CI/CD

Erreurs courantes à éviter

  • Oublier les bindings spécifiques au protocole (Kafka, MQTT)
  • Ne pas valider les payloads avec le schéma AsyncAPI avant le déploiement
  • Ignorer la gestion des versions de messages et les breaking changes
  • Utiliser des clés de partition inconsistantes entraînant des déséquilibres de charge

Pour aller plus loin

Explorez les fonctionnalités avancées comme les multi-protocoles et les tests contractuels. Rejoignez nos formations AsyncAPI avancées pour maîtriser les architectures événementielles à l'échelle.