API Referansı

Main GraphQL HTTP

Oturum açmış istemciler için şifreli istekler.

key = Base64Decode(session.token)Kimliği doğrulanmış oturum; c-id = clientId

İstemci
https://<host>:<port>/graphql
Sunucu

POST /graphql

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

HTTP · binary

JSON({ requestId, query, variables })

requestId UUIDv7'dir ve istek zamanını içerir. variables, operationName ve extensions isteğe bağlıdır.

Her istek için yeni UUIDv7 requestId kullanın. Zamanı sunucuya göre ±30 dakika içinde olmalıdır. UUID tekrarları bellekte elenir.

XChaCha20-Poly1305 · Alanın üzerine gelin veya dokunun
1 / 2

Yeniden oynatma koruması

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Kimlik doğrula ve şifreyi çözsession.token✕ → Reddet
↓
UUIDv7 zamanını doğrula|serverTime − requestId timestamp| ≤ 30 min✕ → Reddet
↓
Çalıştırmadan önce requestId kaydetsession → request-ID set
✓ ↓GraphQL çalıştır
✕ ↓Yeniden kullanılan requestId değerini reddet
Bearer API Token: gövde şifrelemesi olmadan HTTPS üzerinden JSON →
Kitaplık çağrıları

Desktop alıntıları. graphqlRequestPayload UUIDv7 requestId oluşturur. JSON'u HTTP_REQUEST, POST ve mantıksal uç noktayı bağlayan AAD ile şifreleyin, sonra yanıt bağını doğrulayın.

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: Kimliği doğrulanmış oturum yok veya geçersiz. Kayıtlı anahtar, iptal edilene ya da değiştirilene kadar yeniden başlatma sonrasında da geçerlidir. 400: requestId hatalı, süresi geçmiş veya yinelenmiş. 429: Tekrar önleme önbelleği dolu.