La Suite Docs 5.0.0: Neue API, Bruch mit alten Clients

Mit Version 5.0.0 baut La Suite Docs vor allem seine Dokument-API um. Der größte Einschnitt: Inhalt und Metadaten eines Dokuments sind nun getrennt. Laut den offiziellen Release Notes und der Upgrade-Anleitung heißt der bisherige Content-Pfad jetzt formatted-content, das Feld content fällt aus der regulären Dokumentantwort weg und für Lesen sowie Schreiben kommen eigene Endpunkte hinzu. Für bestehende API-Clients ist das ein Breaking Change.

La Suite Docs ist ein quelloffener Editor für die Zusammenarbeit von Teams und versteht sich als souveräne Alternative zu Notion oder Google Docs. Zielgruppen sind öffentliche Einrichtungen ebenso wie Unternehmen. Hinter dem Projekt stehen das deutsche Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) und die französische Interministerielle Behörde für Digitales (DINUM).

Inhalt und Metadaten getrennt

Den Grund für den harten Schnitt nennen die Entwickler im Commit d7a186a. Bisher liefen Inhaltsänderungen über denselben Update-Endpunkt wie andere Dokumenteigenschaften. Selbst beim simplen Umbenennen lieferte der Server den kompletten Inhalt mit aus – und griff dafür unnötig auf den im S3-Speicher abgelegten Dokumentzustand zu. Dafür gibt es jetzt einen eigenen Endpunkt: PATCH /api/v1.0/documents/{document_id}/content/. Die Upgrade-Anleitung zeigt als erwartete Payload ein Base64-codiertes Feld content. Ist der übergebene Dokumentzustand ungültig, antwortet der Server mit 400 Bad Request und der Fehlermeldung invalid yjs document. Wer nur Metadaten wie Titel oder Sichtbarkeit ändert, muss damit nicht mehr den eigentlichen Dokumentinhalt mitschleppen.

Auch zum Lesen gibt es einen eigenen Endpunkt. GET /api/v1.0/documents/{document_id}/content/ streamt den Inhalt laut Upgrade-Anleitung als text/plain. Der Commit 6b3d197 zeigt, dass dafür StreamingHttpResponse und 8192 Byte große Chunks zum Einsatz kommen. Fehlt die Datei im Storage, liefert der Endpunkt trotzdem HTTP 200 mit leerem Body. Die Tests im selben Commit dokumentieren auch die Zugriffsmatrix: Anonyme Nutzer dürfen öffentliche Dokumente abrufen; für nicht öffentliche Dokumente erhalten sie 401. Authentifizierte Nutzer ohne Berechtigung bekommen bei restricted ein 403. Im Code spricht das Projekt von „raw Yjs content“. Yjs ist eine Bibliothek für Echtzeit-Kollaboration, die gemeinsame Datentypen automatisch synchronisiert. Der Endpunkt liefert also eher den kollaborativen Rohzustand eines Dokuments als ein fertig gerendertes Austauschformat.

Konverter und KI-Anbindung umgebaut

Für Selfhoster dürfte die zweite große Nachricht das Upgrade des Konvertierungsdiensts auf DocSpec 3.0.x sein. Pull Request #2220 hält ausdrücklich fest, dass das Docker-Image ghcr.io/docspecio/api:3.0.0 gemeinsam mit dem Anwendungscode aktualisiert werden muss. Das neue Request-Format ist nicht abwärtskompatibel; wer nur eine Seite aktualisiert, riskiert Ausfälle bei der Dokumentkonvertierung. Derselbe Pull Request beschreibt ferner die technische Umstellung: Statt eines Multipart-Uploads schickt der Client den Dokumentinhalt jetzt direkt im Request-Body und setzt Content-Type und Accept explizit. Wer eigene Compose-, Helm- oder Kubernetes-Setups pflegt, muss den Konverter also fest in den Major-Upgrade-Plan einplanen.

Neu ist außerdem eine Mistral-Anbindung für die neue KI-Pipeline. Der Commit b6efac3 führt eine Provider-Auswahl ein, die je nach Konfiguration entweder OpenAIChatModel oder MistralModel verwendet. In der Dokumentation der Umgebungsvariablen tauchen dafür OPENAI_SDK_API_KEY, OPENAI_SDK_BASE_URL, MISTRAL_SDK_API_KEY und MISTRAL_SDK_BASE_URL auf. Die Upgrade-Anleitung benennt zugleich die früheren Variablen AI_API_KEY und AI_BASE_URL in OPENAI_SDK_* um. Wichtig für Betreiber eigener KI-Infrastruktur: Der Mistral-Pfad funktioniert nur im Async-Betrieb mit uvicorn. Für Endanwender ändert sich damit zunächst wenig; die Neuerung zielt auf Installationen, die nicht ausschließlich OpenAI-kompatible Gegenstellen nutzen.

Kleinere Verbesserungen für Betrieb und Frontend

Daneben gibt es in Version 5.0.0 mehrere praxisnahe Updates für Betrieb und UI. Pull Request #2241 begründet den jetzt konfigurierbaren Forward-Auth-Header damit, dass Traefik andere Header-Namen verwendet; per Konfiguration lässt sich der auszulesende Header etwa auf HTTP_X_FORWARDED_URI setzen. Im Frontend wandert die Crisp-Hilfefunktion laut PR #2222 ins Hilfemenü – der bisherige Button habe Teile der App überlagert.

Hinzu kommen kleinere, aber nützliche Korrekturen: Angeheftete Dokumente sortiert das Backend laut PR #2028 nun nach updated_at absteigend und ungültige Verschiebeoperationen im Dokumentbaum quittiert der Server laut PR #2208 mit 400 Bad Request statt mit 500 Internal Server Error. Die Release Notes listen zudem mehrere Verbesserungen bei der Barrierefreiheit und kleinere Frontend-Fixes auf.

Unterm Strich ist Version 5.0.0 kein großes Feature-Release, sondern ein Backend- und Infrastruktur-Umbau mit spürbaren Folgen für API-Clients, Selfhoster und Betreiber eigener Zusatzdienste. Endanwender bekommen vor allem kleinere UI-Verbesserungen zu sehen. Für Integratoren bringt die neue Trennung zwischen Metadaten, formatiertem Inhalt und rohem Inhaltsstream dagegen einige Anpassungen mit sich.

(fo)