API-Referenz

Main GraphQL HTTP

Verschlüsselte Anfragen für eine angemeldete Sitzung.

key = Base64Decode(session.token)Authentifizierte Sitzung; c-id = clientId

Client
https://<host>:<port>/graphql
Server

POST /graphql

c-id: 706c6169-3b80-8f42-9a61-4e312e54d001

HTTP · binary

JSON({ requestId, query, variables })

requestId ist eine UUIDv7 und enthält die Anfragezeit. variables, operationName und extensions sind optional.

Für jede Anfrage eine neue UUIDv7 als requestId verwenden. Ihre Zeit muss innerhalb von ±30 Minuten zur Serverzeit liegen. UUID-Werte werden im Arbeitsspeicher dedupliziert.

XChaCha20-Poly1305 · Feld mit der Maus oder durch Antippen öffnen
1 / 2

Replay-Schutz

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Authentifizieren und entschlüsselnsession.token✕ → Ablehnen
↓
UUIDv7-Zeit prüfen|serverTime − requestId timestamp| ≤ 30 min✕ → Ablehnen
↓
requestId vor der Ausführung speichernsession → request-ID set
✓ ↓GraphQL ausführen
✕ ↓Wiederverwendete requestId ablehnen
Bearer API Token: JSON über HTTPS, ohne Body-Verschlüsselung →
Bibliotheksaufrufe

Desktop-Codeauszüge. graphqlRequestPayload erzeugt eine UUIDv7 als requestId. JSON mit AAD verschlüsseln, das HTTP_REQUEST, POST und den logischen Endpunkt bindet; anschließend die Antwortbindung prüfen.

typescript
// plain-desktop/src/lib/api/gql-client.ts
const payload = graphqlRequestPayload(query, variables)
const requestBody = chachaEncrypt(key, payload, httpRequestAad('/graphql'))
const response = await httpRequest(url, {
  method: 'POST', headers: { 'c-id': clientId }, body: requestBody
})
if (!response.ok) throw new Error(String(response.status))
const bytes = new Uint8Array(await response.arrayBuffer())
const result = JSON.parse(decryptGraphqlResponse(key, requestBody, bytes))
// Feature error codes are carried in extensions.code; message is diagnostic text.
if (result.errors?.length) throw GqlError.fromGraphql(result.errors[0])

HTTP 401: Die authentifizierte Sitzung fehlt oder ist ungültig. Ein gespeicherter Sitzungsschlüssel bleibt nach einem Neustart gültig, bis er widerrufen oder ersetzt wird. 400: ungültige, abgelaufene oder doppelte requestId. 429: Replay-Cache voll.