Публічний API

Для розробників

GraphQL API

На сьогодні це єдиний загально доступний формат обміну даними котрий може задовольнити потреби будь-якого типу клієнта. Документація одразу вбудована в точку доступу, а зручний інструментарій виводить досвід розробника на новий рівень.

Якщо у Вас досі не було досвіду роботи з GraphQL API радимо ознайомитись з найкращим ресурсом для новачків - https://www.howtographql.com/

Точка доступу

https://api.keruj.com/api/graphql

Клієнт

Ви можете використовувати будь-який http клієнт для виконання запитів, що вміють виконувати POST запити. А тут є класна стаття з оглядами на загально відомі GUI клієнти.

Документація

Для максимальної зручності ми підготували для Вас пісочницю котра одразу підключення до публічної точки API https://graphiql.keruj.app/. Вам варто тільки додати свої хедери авторизації та одразу зможете випробувати усі потужності нашого GraphQL API

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

Уся взаємодія Керуй відбувається від імені користувача, тому що враховуються права доступу. Вам знадобиться API ключ користувача та id поточної компанії.

На вашому порталі перейдіть в головному меню Учасники.
Оберіть потрібного вам учасника або створіть нового тільки для API доступу.
На вкладці “Доступ” натисніть “Додати” в розділі API

У вікні справа отримайте API ключ та збережіть у безпечному місці. Це дуже важливий крок, адже ви більше ніколи цей ключ не зможете отримати. Не передавайте ключ третім особам, тому що це питання безпеки ваших даних.

На цій же сторінці ви можете отримати інформацію для заголовка x-current-company-id. Він нам знадобиться для авторизації запитів.

У нашому веб застосунку для тестування API - https://graphiql.keruj.app

Приклад запиту на отримання інформації про поточного користувача

query {
  me {
    currentAccount {
      displayName
      position
      role {
        name
      }
    }
  }
}

A) Можна ознайомитись з вбудованою документацією

B) Створити запит як query або mutation

C) Вказати автентифікаційні заголовки x-tokenта x-current-company-id

{
  "x-token": "your_account_token",
  "x-current-company-id": "your_company_id"
}

D) Отримати результат

Query запити

Query це аналог GET запиту з REST API, але ви можете самі вказати який формат відповіді Вам потрібен. Радимо активно використовувати змінні та запитувати тільки ті поля, що потрібні вам для роботи. Це допоможе швидше та ефективніше формувати відповіді та не перевантажувати мережу зайвими даними

Приклад запиту на отримання переліку завдань за пошуком по ключовому слову

query($search: String, $filter: TasksFilter, $first: Int, $after: String) {
 listTasks(search: $search, filter: $filter, first: $first, after: $after) {
   edges {
     node {
       id
       title
       status
     }
   }
   pageInfo {
     startCursor
     endCursor
     hasNextPage
     hasPreviousPage
   }
 }
}

Mutation запити

Mutation це аналог POST/PUT/DELETE запитів з REST. Використовуються для створення, зміни або видалення даних. На вхід як правило передається певний Input тип даних, а у відповідь ви отримуєте необхідну вам структуру.

Приклад запиту на створення нового завдання

mutation ($input: CreateTaskInput!) {
  createTask(input: $input) {
    title
    creator {
      id
      displayName
    }
  }
}

Помилки

Нагадуємо, що в GraphQL немає статус кодів, а усі запити повертаються як 200. Зважайте на вміст data та errors у відповіді

Обмеження у кількості запитів

Кожен учасник має обмеження у 200 запитів на хвилину на 1 сервер. Для звичайної роботи цього вистачає абсолютно, але для імпорту великих масивів даних краще ставити паузи між запитами у 300ms, щоб не потрапити у блокування до кінця поточної хвилини.

Отримати інформацію про поточний ліміт завжди можна із запиту

query {
  me {
    currentLimit {
      count
      remaining
      nextLimitAt
    }
  }
}