Skip to main content
On this page

CQRS

Die Schnittstellenarchitektur von etg24 basiert konsequent auf dem Prinzip der Command Query Responsibility Segregation (CQRS). Anstelle überladener REST-Endpunkte, bei denen Seiteneffekte oft unklar sind, ist jede Operation eindeutig als reine Leseoperation (Query) oder zustandsändernde Schreiboperation (Command) definiert.

Queries versus Commands

  • Queries lesen Daten aus dem System, ohne den Zustand zu verändern. Sie sind idempotent, fehlertolerant beliebig oft wiederholbar und können gefahrlos mit reinen Lese-Schlüsseln (Read-only) ausgeführt werden.
  • Commands verändern den Systemzustand – sie legen Datensätze an, bearbeiten oder archivieren sie. Commands führen Validierungen durch, lösen Domänen-Events aus und schreiben lückenlose Einträge in das Audit-Log.

In der REST-API wird diese Trennung unmittelbar im URL-Pfad sichtbar:

GET  /propertymanagement/v2/query/contacts           Paginierte Kontaktliste abrufen
GET  /propertymanagement/v2/query/contacts.show      Einzelnen Kontakt anhand der ID laden
POST /propertymanagement/v2/command/contacts.create  Neuen Kontakt anlegen
POST /propertymanagement/v2/command/contacts.update  Bestehenden Kontakt aktualisieren

Auch der MCP-Server setzt dieses Paradigma nahtlos fort: Jedes Werkzeug im Tool-Katalog ist als Query- oder Command-Tool gekennzeichnet. Ein autonomer Agent kann Query-Tools gefahrlos zur Kontextgewinnung nutzen, während schreibende Commands nur gezielt ausgeführt werden.

Praktische Vorteile für deine Integration

  1. Eindeutige Sicherheitsgrenzen: Read-only-Scopes greifen exklusiv auf Queries zu. Ein Schlüssel mit reinem Lesezugriff kann systemweit alle berechtigten Daten abrufen, schreibende Commands werden bereits am API-Gateway blockiert. Siehe Berechtigungs-Scopes.
  2. Revisionssichere Nachvollziehbarkeit: Jeder Command wird mit Akteur-ID, Eingabeparametern und Ergebnisänderung unveränderlich erfasst. Siehe Audit-Trail & Änderungszuordnung.
  3. Reversibilität im Fehlerfall: Da Commands gezielte Fachoperationen abbilden und Löschvorgänge als Soft Deletes ausgeführt werden, können unerwünschte Änderungen strukturiert rückgängig gemacht werden. Siehe Soft Delete & Rollback.

Best Practice für Agenten und Integrationen

Für Entwickler und Prompts gilt eine einfache Faustformel:

  • Queries nutzen, um Kontext zu laden, Status abzufragen und Informationen zusammenzutragen – völlig risikofrei und retry-sicher.
  • Commands nutzen, sobald Daten verbindlich gespeichert oder Folgeprozesse angestoßen werden sollen (z. B. das Anlegen eines Vorgangs oder das Buchen einer Rechnung). Parameter sollten vor dem Command-Aufruf stets validiert werden.