Entwurf ereignisgesteuerter Architekturen mit AsyncAPI

AsyncAPI: Ein Open-Source-Tool, mit dem ereignisgesteuerte Architekturen auf einfache Weise dokumentiert werden können.

Ereignisgesteuerte Architekturen (EDA)

Eine ereignisgesteuerte Architektur (Event Driven Architecture, EDA) ist ein vielversprechender Ansatz für Softwarearchitekturen. Im Gegensatz zu traditionellen, zustandsbasierten Architekturen, bei denen Anfragen an das System gesendet werden und eine sofortige Antwort erwartet wird, kommunizieren die Komponenten in einer EDA durch das Senden und Empfangen von Ereignissen. Bei diesen Ereignissen kann es sich um Benutzerinteraktionen, Änderungen des Systemzustands oder externe Benachrichtigungen handeln.

EDA ermöglicht eine skalierbare und flexible Systemarchitektur, die sich besonders gut für moderne, verteilte und/oder Microservice-Anwendungen eignet.

Entwicklung und Dokumentation von EDA's

Hier kommt AsyncAPI ins Spiel, ein Open-Source-Tool und gleichzeitig ein Standard, der speziell für die Dokumentation, den Entwurf und die Implementierung ereignisgesteuerter Architekturen (EDAs) entwickelt wurde.

Es bietet eine Spezifikation, welche die Schnittstellen von asynchronen APIs definiert, ähnlich wie OpenAPI (früher bekannt als Swagger) für REST-APIs. AsyncAPI erleichtert die Dokumentation von ereignisgesteuerten Systemen auf verschiedenen Ebenen (z. B. Build-Level, Server, Client), automatisiert die Generierung von Code aus AsyncAPI-Spezifikationen in verschiedenen Programmiersprachen und erfreut sich einer aktiven Community.

Da AsyncAPI protokollunabhängig ist, unterstützt es verschiedene Messaging-Protokolle wie AMQP, MQTT, WebSockets, Kafka und HTTP und ist damit ein wertvolles Werkzeug für die Entwicklung robuster und skalierbarer ereignisgesteuerter Anwendungen.

Vergleich von AsyncAPI mit OpenAPI

OpenAPI und AsyncAPI sind beides Spezifikationen zur Beschreibung von APIs, die sich jedoch in einigen wichtigen Punkten unterscheiden:

• Schwerpunkt: OpenAPI konzentriert sich auf synchrone REST-APIs, während AsyncAPI speziell für asynchrone APIs entwickelt wurde.
• Protokolle: OpenAPI ist protokollspezifisch (meist HTTP), während AsyncAPI protokollunabhängig ist und z. B. AMQP, MQTT, WebSockets, Kafka, STOMP und HTTP unterstützt.
• Ereignisse: AsyncAPI bietet erweiterte Funktionen für die Beschreibung von Ereignissen, wie Schemata, Datenformate und Routing.

Beispiel

Es folgt ein einfaches Beispiel einer AsyncAPI-Spezifikation für eine API, die Ereignisse verarbeitet, welche beim Eintreffen neuer Aufträge an einen Kafka Broker gesendet werden.

asyncapi: 3.0.0
info:
  title: Order Placed API
  version: '1.0.0'
  description: This API handles events related to placing new orders in the system.

servers:
  production:
    host: letsboot.com:9092
    protocol: kafka
    description: Apache Kafka broker - Production

  local:
    host: localhost:9092
    protocol: kafka
    description: Apache Kafka broker - Local Development

channels:
  order_placed:
    address: order_placed
    messages:
      subscribe.message:
        $ref: '#/components/messages/OrderPlacedEvent'
    description: Topic for order placed events


operations:
  order_placed.subscribe:
    action: send
    channel:
      $ref: '#/channels/order_placed'
    messages:
      - $ref: '#/channels/order_placed/messages/subscribe.message'

components:
  messages:
    OrderPlacedEvent:
      name: OrderPlacedEvent
      title: Order Placed Event
      summary: Inform about a new order placed in the system
      payload:
        type: object
        properties:
          userId:
            type: string
            format: uuid
          orderId:
            type: string
            format: uuid
          timestamp:
            type: string
            format: date-timer

Grundsätzlich könnte man annehmen, dass die obige Beschreibung als Eingabe für Code-Generatoren verwendet werden kann. Derzeit ist die Unterstützung dieser Code-Generatoren auf der Website von AsyncAPI für Version 3.0.0 noch nicht vollständig fehlerfrei. Ein Beispiel dafür ist das Ergebnis des Versuchs, das Java-Spring-Template zu nutzen, welches folgenden Fehler ausgibt:

"Error: @asyncapi/java-spring-template template does not support AsyncAPI v3 documents"

Jedoch ist es wahrscheinlich, dass die Code-Generierung bald auch für die aktuelle Version 3.0.0 oder höher reibungslos funktionieren wird.

Fazit

Obwohl die Code-Generierung für AsyncAPI-Versionen 3.0.0 und höher derzeit noch nicht einwandfrei funktioniert, bietet die AsyncAPI-Beschreibung dennoch einen Mehrwert. Sie dient nicht nur als Eingabe für automatisierte Code-Generatoren, sondern kann auch als Vorlage für manuelle Implementierungen verwendet werden. Entwickler können die Beschreibung nutzen, um APIs auf traditionelle Weise umzusetzen, insbesondere wenn die Code-Generierung nicht verfügbar oder nicht optimal ist.

Somit bleibt die AsyncAPI-Spezifikation trotz der aktuellen Einschränkungen eine wertvolle Ressource für die API-Entwicklung.