Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Schreibzugriff

Gilt für

Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator · Administrator

Werkzeuge, die etwas in einem externen System verändern: Bestätigungsmuster, Idempotenz und was basebox vor einer Schreiboperation erwartet. In basebox sind alle schreibfähigen Werkzeuge je App standardmäßig deaktiviert; ein Administrator muss sie ausdrücklich freigeben. Entwerfen Sie sie so, dass diese Freigabe leichtfällt.

Grundsatz: Schreiben ist eine eigene Klasse

• Eigene Werkzeuge für Änderungen – create_issue, update_page, add_comment – klar von Lesewerkzeugen getrennt. Nie ein Werkzeug, das je nach Parameter liest oder schreibt.
• Sprechende Namen, an denen basebox und Administratoren die Klasse erkennen: create_*, update_*, delete_*.
• Beschreibung nennt die Wirkung: „Legt ein neues Issue an. Ändert Daten im Ticketsystem."

So kann eine App breit mit Lesewerkzeugen freigegeben werden, während Schreibwerkzeuge nur in einer eng freigegebenen App aktiv sind – siehe Konnektor-Berechtigungen.

Immer mit den Zugangsdaten der Person

Eine Änderung erfolgt als der Nutzer, dessen Token im Authorization-Header steht. Im Zielsystem erscheint sie unter seinem Namen; das Zielsystem prüft, ob er sie durchführen darf. Schreibwerkzeuge über ein Servicekonto sind ein Anti-Pattern: Änderungen wären niemandem zuzuordnen, und das Servicekonto bräuchte Schreibrechte für alle.

Muster für sichere Schreibwerkzeuge

Explizite, vollständige Parameter. Ein Schreibwerkzeug rät nichts. update_issue braucht die Issue-ID und exakt die zu ändernden Felder; kein „passe das Issue an, das der Nutzer meint".

Kleine Wirkung je Aufruf. Ein Objekt je Aufruf. Keine Massenoperationen (delete_all, update_matching) – wenn zehn Issues geändert werden sollen, sind das zehn nachvollziehbare Aufrufe.

Idempotenz. Ein wiederholter Aufruf mit denselben Parametern darf keine zweite Wirkung haben. Nutzen Sie Idempotenz-Schlüssel des Zielsystems, prüfen Sie vor dem Anlegen auf Duplikate oder bieten Sie update statt create an, wo das Zielsystem es erlaubt.

Zustand zurückgeben. Das Ergebnis enthält, was geändert wurde – ID, Link, die neuen Feldwerte, idealerweise vorher/nachher. Das Modell kann dem Nutzer damit exakt berichten, und der Nutzer kann prüfen.

Löschen vermeiden. Wo möglich, „archivieren", „schließen" oder „als erledigt markieren" statt löschen. Ist Löschen nötig, nur einzeln, nur per ID, mit vollständiger Rückmeldung.

Vorschau anbieten. Ein dry_run-Parameter oder ein getrenntes preview_*-Werkzeug zeigt, was passieren würde – und das Modell kann den Nutzer fragen, bevor es schreibt.

Was basebox vor einer Schreiboperation erwartet

1. Der Konnektor ist organisationsweit aktiv und das Schreibwerkzeug ist in der aktuellen App ausdrücklich freigegeben.
2. Der Nutzer hat eigene Zugangsdaten hinterlegt; ohne sie wird das Werkzeug dem Modell nicht angeboten.
3. Der Aufruf trägt den Header des Nutzers; das Zielsystem entscheidet, ob die Änderung erlaubt ist.
4. Das Ergebnis wird als Daten gerahmt und dem Nutzer angezeigt; der Aufruf steht im Audit-Log (Nutzer, Werkzeug, Ziel, Ergebnis, Zeitstempel).

Eine zusätzliche Freigabe durch einen Menschen vor dem Aufruf (Human-in-the-Loop) ist angekündigt, aber noch nicht verfügbar. Bis dahin liegt die Bestätigung im Design Ihrer Werkzeuge: kleine Wirkung, Vorschau, klare Rückmeldung.

Fehler und Konflikte

Situation	Verhalten
Zielsystem verweigert (403)	Als Ergebnis melden; nichts umgehen
Objekt inzwischen geändert (Konflikt, 409)	Melden, aktuelle Version zurückgeben, nicht überschreiben
Validierungsfehler (400)	Fehlende oder ungültige Felder benennen, damit das Modell nachfragen kann
Timeout nach dem Senden	Nicht blind wiederholen; Status per get prüfen, dann berichten
Teilweise erfolgreich	Genau sagen, was gelang und was nicht

Beispiel: Ergebnis eines Schreibwerkzeugs

{
  "action": "update_issue",
  "id": "PROJ-123",
  "url": "https://tickets.example.com/issue/PROJ-123",
  "changed": {
    "state": {"from": "Open", "to": "In Progress"},
    "assignee": {"from": null, "to": "m.mueller"}
  }
}

Checkliste vor der Freigabe

• Schreibwerkzeuge getrennt und als solche benannt
• Nur mit persönlichen Zugangsdaten
• Ein Objekt je Aufruf, keine Massenoperationen
• Idempotent; Duplikate vermieden
• Vollständige Rückmeldung mit ID, Link, geänderten Feldern
• Löschen vermieden oder eng begrenzt
• Dokumentiert, in welchen Apps das Werkzeug freigegeben werden soll

Weiter: Berechtigungen · Beispiele