Работа с 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 можно ознакомиться по ссылкам:

• официальный сайт и документация;
• https://medium.com/the-graphqlhub/graphiql-graphql-s-killer-app-9896242b2125;
• https://medium.com/graphql-mastery/graphql-quick-tip-how-to-pass-variables-into-a-mutation-in-graphiql-23ecff4add57.

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

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

• авторизуйтесь в Proceset;
• перейдите по адресу: адрес_системы/graphiql.

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

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

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

Примеры запросов 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” 
                ] 
            } 
        } 
    } 
}