Работа с GraphQL

Описание GraphQL

В качестве API система Proceset использует технологию GraphQL. GraphQL — это язык запросов для API с открытым исходным кодом, который обеспечивает более эффективную и гибкую альтернативу классическому REST. В то время как типичные API REST требуют загрузки с нескольких URL-адресов, API GraphQL позволяет получить необходимые данные в одном запросе.

Для создания и выполнения GraphQL-запросов можно использовать встроенную браузерную IDE (интегрированную среду разработки) GraphiQL. Чтобы получить к ней доступ, перейдите на страницу системы и в адресной строке введите адрес_системы/graphiql.

Когда вы редактируете запрос во встроенной IDE, URL-адрес также обновляется. При этом сохраняются пробелы, комментарии и неверные запросы. Вы можете пересылать URL-ссылки другим коллегам.

GraphQL-запросы являются интерактивными. Это означает, что вы можете изменить запрос и увидеть новый результат.

GraphQL API поддерживает автогенерацию документации. Документация всегда в актуальном состоянии. Для ее просмотра откройте вкладку Docs (находится в правом верхнем углу) на странице встроенной IDE. В этом разделе представлены все запросы, которые можно выполнить в Proceset.

GraphQL-запросы в системе разделены по типу на три группы:

• query
• mutation
• subscription

Выберите нужную группу и найдите интересующий запрос.

В описании каждого запроса представлены список полей и их типы данных.

С дополнительной информацией по работе с GraphQL можно ознакомиться на официальном сайте.

Описание способов аутентификации и способов работы с GraphiQL

Для более удобного формирования и выполнения запросов в систему включена встроенная IDE GraphiQL. Чтобы её использовать:

1. Авторизуйтесь в Proceset.
2. Перейдите по адресу: адрес_системы/graphiql.

Для выполнения запроса из внешней системы необходимо подготовить ключ API для аутентификации в разделе «Настройки» / «Ключи API». Для подключения внешних систем возможны два режима аутентификации через ключи API:

• стандартный ключ API представляет собой последовательность символов, которую должна будет предъявлять внешняя система для аутентификации
• SSL-сертификат. Внешняя система для аутентификации сначала предоставляет API-ключ, затем происходит взаимная аутентификация систем на основе SSL-сертификатов

Назначьте привилегии созданному ключу API. Подробнее о настройке привилегий ключам API см. Права доступа для ключей API.

Запрос от имени ключа API

Чтобы GraphQL-запрос был от имени ключа API, необходимо в адресной строке ввести ключ.

Пример:

https://automation-dev.preview.infomaximum.com/graphql?api_key=ключ

Примеры запросов GraphQL

Далее приведены некоторые GraphQL-запросы, которые могут быть использованы в системе.

Получение рабочего пространства

Запрос:

{ 
    workspace { 
        workspace (id: 273) { 
            id 
            name 
        } 
    } 
} 

Ответ:

{ 
    "data": { 
        "workspace": { 
            "workspace": { 
            "id": 273, 
            "name": "test"
            } 
        } 
    } 
} 

Создание сотрудника

Запрос:

mutation { 
    employee { 
        create ( 
            login: "test"
            first_name: "Ivan"
            second_name: "Ivanov" 
            language: RUSSIAN 
            phone_numbers: "12345678901" 
        ){ 
            id 
            login 
            first_name 
            second_name 
            language 
            phone_numbers 
        } 
    } 
} 

Ответ:

{ 
    "data": { 
        "employee": { 
            "create" { 
                "id": 244, 
                "login": "test", 
                "first_name": "Ivan", 
                "second_name": "Smirnov", 
                "language": "RUSSIAN", 
                "phone_numbers": [ 
                    "12345678901" 
                ] 
            } 
        } 
    } 
} 

Получение сотрудников с конкретной ролью доступа

Запрос:

{
    access_role {
        access_role (id:171) {
            employees {
                items {
                    id
                    first_name
                    second_name
                }
            }
        }
    }
}

Ответ:

{
  "data": {
    "access_role": {
      "access_role": {
        "employees": {
          "items": [
            {
              "id": 82,
              "first_name": "Алексей",
              "second_name": "Смирнов"
            },
            {
              "id": 142,
              "first_name": "Анна",
              "second_name": "Демидова"
            },
            {
              "id": 143,
              "first_name": "Вероника",
              "second_name": "Свердлова"
            },
            {
              "id": 141,
              "first_name": "Дмитрий",
              "second_name": "Аксенов"
            }
          ]
        }
      }
    }
  }
}