Für Entwickler

Die Sync-API verwenden

Lies und schreibe freigegebene JSON-Dokumente mit Bearer-Tokens und bedingten Requests.

4 Min. LesezeitStand: 18. Oktober 2026

Zugang und Pfade#

Die Basis-URL ist https://account.julianverse.de. Jeder Aufruf benötigt ein gültiges Access-Token mit Scope sync, das zu genau dieser App gehört. Die ownCloud-Verbindung muss bereit sein. Für eine konkrete Ressource muss zusätzlich die Nutzerfreigabe aktiv sein.

APP-ID ist die registrierte App-Kennung aus config.app, nicht die OAuth-Client-ID. DATENART ist ein registrierter Schlüssel wie notes.

Methode und Pfad Ergebnis
GET /api/sync/APP-ID Konto-ID und Freigabestatus der Datenarten
GET /api/sync/APP-ID/DATENART JSON-Dokument und starker ETag
PUT /api/sync/APP-ID/DATENART Bedingtes Erstellen oder Aktualisieren

Ein allgemeiner Datei- oder Verzeichniszugriff und ein DELETE-Endpunkt gehören nicht zu dieser API. Verwende für die vorhandene App-Integration bevorzugt das SDK.

Freigaben prüfen#

Beispiel für einen Status-Response:

{
  "app": "app-DEINE_APP_KENNUNG",
  "subject": "KONTO_ID",
  "resources": {
    "notes": true,
    "settings": false
  }
}

Eine Freigabe bedeutet, dass die App auf die Ressource zugreifen darf. Die erste Übertragungsrichtung muss weiterhin bewusst gewählt werden. Ein false darf nicht durch einen automatischen Upload umgangen werden.

Dokumentformat#

{
  "schemaVersion": 1,
  "data": {
    "value": { "text": "Meine Notiz" }
  },
  "deleted": false
}

Der Account verlangt einen JSON-Objektumschlag mit schemaVersion: 1, data und, sofern vorhanden, einem booleschen deleted. Das App-eigene Format unter data prüft die App. Der generische SDK-Adapter verwendet data.value.

Selbst registrierte Apps dürfen höchstens 512 KiB je Datei inklusive Umschlag speichern. Die 8-MiB-Ausnahme für Julianverse News gilt nicht für beliebige eigene Apps. Löschungen innerhalb des Sync-Protokolls werden als gültiges Dokument mit deleted: true dargestellt.

Lesen#

GET /api/sync/APP-ID/notes HTTP/1.1
Host: account.julianverse.de
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

Bewahre den erhaltenen ETag unverändert und inklusive Anführungszeichen zusammen mit der gelesenen Version auf. Ein unbekannter oder schwacher ETag ist keine sichere Grundlage für einen Schreibzugriff.

Eine vorhandene Datei aktualisieren#

PUT /api/sync/APP-ID/notes HTTP/1.1
Host: account.julianverse.de
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
If-Match: "GELESENER_ETAG"

{"schemaVersion":1,"data":{"value":{"text":"Geändert"}},"deleted":false}

Für eine erstmalig anzulegende Datei verwendest du stattdessen nur If-None-Match: *. Verwende nie beide Schreibbedingungen gleichzeitig. Ein bedingter Create ist erst sinnvoll, nachdem der fehlende Stand und die ausdrückliche Initialisierung geklärt wurden.

Der erfolgreiche Response enthält saved: true und den vom Speicher gelieferten ETag, sofern vorhanden. Erfinde keine Dateiversion und verwende keinen unbedingten Folgeschreibzugriff. Ein späteres Lesen kann bereits eine weitere Änderung enthalten.

Fehler sinnvoll behandeln#

Status Typischer Anlass Reaktion
401 Token ungültig oder abgelaufen Zugang erneuern beziehungsweise neu anmelden
403 Fehlender Scope, falsche App oder ausgeschaltete Datenfreigabe Berechtigungen prüfen und nicht automatisch aktivieren
404 Datei oder Ressource nicht vorhanden Ressourcenschlüssel und Initialisierung prüfen; lokale Kopie behalten
409 Cloud nicht verbunden oder Dokument ungültig Verbindung beziehungsweise vorhandenen Inhalt prüfen
412 Cloud-Version wurde parallel geändert Beide Versionen erhalten und Entscheidung anbieten
413 Datei zu groß Lokale Daten behalten, Inhalt verkleinern oder anderes Speicherverfahren wählen
428 Schreibbedingung fehlt oder ist ungültig Exakten ETag oder bedingten Create verwenden
429 Rate-Limit erreicht Anfragen drosseln und später erneut versuchen
502 Cloud-Lesen oder -Schreiben fehlgeschlagen Sichtbaren Fehler melden und lokale Änderungen erhalten

Für Sync-Zugriffe gilt derzeit ein Limit von 120 Anfragen pro Minute je Nutzer. Fehlerantworten können je nach Schicht JSON oder eine Fehlerseite enthalten; prüfe Status und Content-Type vor dem Parsen.

Konflikte und Wiederholungen#

Bei 412 liest du die aktuelle Cloud-Version, erhältst die lokale Änderung und lässt den Nutzer auswählen oder führst eine nachweislich passende app-eigene Zusammenführung durch. Überschreibe nicht automatisch mit der lokalen Version.

Ein Netzfehler bedeutet nicht „Datei gelöscht“. Nach unklarem Ausgang eines Schreibzugriffs darfst du nicht blind einen unbedingten Upload wiederholen. Das SDK hält lokale Arbeitskopien, ausstehende Änderungen und Versionsbezüge für diese Fälle bereit.

Markdown herunterladen