Справочник API

Main GraphQL HTTP

Зашифрованные запросы для сеанса после входа.

key = Base64Decode(session.token)Аутентифицированный сеанс; c-id = clientId

Клиент
https://<host>:<port>/graphql
Сервер

POST /graphql

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

HTTP · binary

JSON({ requestId, query, variables })

requestId имеет формат UUIDv7 и содержит время запроса. variables, operationName и extensions необязательны.

Для каждого запроса используйте новый requestId UUIDv7. Его время должно отличаться от времени сервера не более чем на ±30 минут. Значения UUID дедуплицируются в памяти.

XChaCha20-Poly1305 · Наведите указатель на поле или коснитесь его
1 / 2

Защита от повторов

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Проверить подлинность и расшифроватьsession.token✕ → Отклонить
↓
Проверить время UUIDv7|serverTime − requestId timestamp| ≤ 30 min✕ → Отклонить
↓
Записать requestId до выполненияsession → request-ID set
✓ ↓Выполнить GraphQL
✕ ↓Отклонить повторный requestId
Bearer API Token: JSON через HTTPS без шифрования тела →
Вызовы библиотеки

Фрагменты Desktop. graphqlRequestPayload создаёт requestId UUIDv7. Зашифруйте JSON с AAD, связывающим HTTP_REQUEST, POST и логическую конечную точку, затем проверьте привязку ответа.

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: аутентифицированный сеанс отсутствует или недействителен. Сохранённый ключ сеанса остаётся действительным после перезапуска до отзыва или замены. 400: некорректный, просроченный или повторный requestId. 429: кэш защиты от повторов заполнен.