---
title: Die Sync-API verwenden
description: Lies und schreibe freigegebene JSON-Dokumente mit Bearer-Tokens und bedingten Requests.
order: 40
updated: 2026-10-18
keywords: api, rest, sync api, json, get, put, etag, if-match, if-none-match, 401, 403, 404, 409, 412, 413, 428, 429, 502
videos: []
---
## 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](/docs/entwicklung/sdk/).

## Freigaben prüfen

Beispiel für einen Status-Response:

```json
{
  "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

```json
{
  "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

```http
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

```http
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.