Tham chiếu API

Main GraphQL HTTP

Yêu cầu mã hóa cho phiên đã đăng nhập.

key = Base64Decode(session.token)Phiên đã xác thực; c-id = clientId

Máy khách
https://<host>:<port>/graphql
Máy chủ

POST /graphql

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

HTTP · binary

JSON({ requestId, query, variables })

requestId là UUIDv7 và chứa thời gian yêu cầu. variables, operationName và extensions là tùy chọn.

Dùng requestId UUIDv7 mới cho mỗi yêu cầu. Thời gian của nó phải nằm trong ±30 phút so với máy chủ. Giá trị UUID được loại trùng trong bộ nhớ.

XChaCha20-Poly1305 · Di chuột hoặc chạm một trường
1 / 2

Chống phát lại

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Xác thực và giải mãsession.token✕ → Từ chối
↓
Kiểm tra thời gian UUIDv7|serverTime − requestId timestamp| ≤ 30 min✕ → Từ chối
↓
Lưu requestId trước khi thực thisession → request-ID set
✓ ↓Thực thi GraphQL
✕ ↓Từ chối requestId đã dùng
Bearer API Token: JSON qua HTTPS, không mã hóa phần thân →
Lệnh gọi thư viện

Trích đoạn Desktop. graphqlRequestPayload tạo requestId UUIDv7. Mã hóa JSON với AAD ràng buộc HTTP_REQUEST, POST và điểm cuối logic, rồi xác minh ràng buộc phản hồi.

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: Thiếu phiên đã xác thực hoặc phiên không hợp lệ. Khóa đã lưu vẫn có hiệu lực sau khi khởi động lại, cho đến khi bị thu hồi hoặc thay thế. 400: requestId sai định dạng, đã cũ hoặc bị trùng. 429: Bộ nhớ đệm chống phát lại đã đầy.