Skip to Content
Elido is in closed beta — APIs are stable but rate-limits and quotas may change before GA. Request access →
ПосібникиGraphQL API

GraphQL API

Elido надає кінцеву точку GraphQL разом із REST API. Кожне поле GraphQL реалізовано як тонкий прошарок до тих самих кінцевих точок api-core, які використовує REST, тому все, що ви можете робити через GraphQL, ви також можете робити через REST - обирайте те, що краще підходить для вашого інтерфейсу.

Кінцева точка - POST /graphql, розміщена на сервісі graphql-gateway. Автентифікація ідентична REST: надішліть свій API-токен або OAuth2 токен доступу в заголовку Authorization: Bearer <token>.

Це базовий випуск. Підписки (кліки в реальному часі), збережені запити, федерація та кешування відповідей є в планах розвитку - дивіться ADR-0031  для повного списку відкладених завдань.

Коли використовувати GraphQL замість REST

  • Використовуйте GraphQL, коли екрану потрібно 4+ ресурси, об’єднані разом (робоча область + посилання + останні кліки + топ-N) - об’єднайте декілька запитів в один, сформований під потреби екрана.
  • Використовуйте GraphQL для мобільних екранів, де обсяг даних та кількість запитів мають значення у нестабільних мережах.
  • Використовуйте REST + SDK для всього іншого. Вебхуки, масове завантаження даних, вивантаження файлів та інструменти адміністрування орієнтовані на REST і залишаться такими.

Автентифікація

curl -X POST https://api.elido.app/graphql \
  -H "Authorization: Bearer $ELIDO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id email } }"}'

API-токени ek_… (особисті токени доступу, токени робочих областей) та OAuth2 токени доступу працюють однаково. Публічні запити інтроспекції, як-от { __schema { types { name } } }, працюють без токена під час розробки; у продакшн-середовищах інтроспекція обмежена параметром GRAPHQL_INTROSPECTION=true.

Приклади

1. Головна панель керування - поточний користувач + список робочих областей

query DashboardLanding {
  me {
    id
    email
    fullName
    timezone
  }
  workspaces {
    id
    name
    role
    planTier
  }
}

Один запит, дві кінцеві точки REST, об’єднані в одну відповідь. Мобільний додаток використовує це як перший автентифікований запит після входу.

2. Посилання робочої області - пагінація у стилі Relay

query WorkspaceLinks($workspaceId: ID!, $after: String) {
  links(workspaceId: $workspaceId, first: 50, after: $after) {
    edges {
      node {
        id
        slug
        destinationUrl
        title
        status
        tags
        createdAt
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Передайте pageInfo.endCursor з попередньої відповіді як наступний параметр after, щоб отримати наступну сторінку. hasNextPage має значення false, коли ви досягли кінця. Курсори є непрозорими - не декодуйте їх.

3. Огляд аналітики - часові ряди + топові посилання одним запитом

query Overview(
  $workspaceId: ID!
  $from: DateTime!
  $to: DateTime!
) {
  timeseries(
    workspaceId: $workspaceId
    from: $from
    to: $to
    interval: "day"
  ) {
    ts
    count
  }
  topLinks(
    workspaceId: $workspaceId
    from: $from
    to: $to
    limit: 10
  ) {
    slug
    clicks
  }
}

from/to - це мітки часу ISO-8601. interval приймає значення "hour" або "day"; api-core перевіряє їх і повертає помилку для будь-яких інших значень. Екран огляду на панелі керування виконує саме цей запит - GraphQL об’єднує те, що раніше було двома викликами REST, в один.

4. Мутації - створення короткого посилання

mutation CreateLink($input: CreateLinkInput!) {
  createLink(input: $input) {
    id
    slug
    destinationUrl
    createdAt
  }
}

Змінні:

{
  "input": {
    "workspaceId": "1",
    "destinationUrl": "https://example.com/launch",
    "tags": ["marketing", "q4"]
  }
}

Мутації посилань доповнюють updateLink(workspaceId, linkId, input) та deleteLink(workspaceId, linkId). Як і в REST, мутації є ідемпотентними на стороні сервера - шлюз пересилає заголовок Idempotency-Key, автоматично згенерований SDK.

Чого немає в цьому випуску

Це навмисні пропуски для початкової фази. Кожна функція з’явиться як окреме оновлення з приміткою щодо міграції:

  • Підписки - події кліків у реальному часі. Транспорт WebSocket, мости до Redis, де analytics-api вже публікує clicks:link:<id>.
  • Збережені запити - продакшн-збірки постачатимуться з маніфестом, хешованим тільки для довірених клієнтів. Наразі ad-hoc запити цілком прийнятні.
  • Федерація - аналітика та білінг є хорошими кандидатами на володіння власними підграфами у майбутньому.

Ліміти та конвенції

  • Такі самі ліміти запитів на токен, як і в REST (повідомляються через заголовки X-RateLimit-* у відповіді GraphQL).
  • Помилки відповідають специфікації GraphQL - масив errors верхнього рівня; часткові дані все ще можуть бути присутніми в data.
  • ID передаються як рядки ("1", а не 1), щоб підтримувати безпеку BigInt-ідентифікаторів у всій схемі.
MCP-серверПровайдер Terraform