Работа с GraphQL через Hasura для системных аналитиков и QA

Цель данной статьи — рассказать о GraphQL и Hasura человеку, который вообще ничего не слышал об этих инструментах. И, например, его карьерный путь сложился так, что ему необходимо иметь общее представление об этих инструментах и даже с ними взаимодействовать, например, для проведения тестирования. Или же ситуация иная: человек постоянно развивается, изучая новые архитектурные подходы, следит за популярными и новыми инструментами и сейчас в своем обучении дошел до GraphQL и Hasura.

Я аналитик, который сам недавно оказался в ситуации первого типа (вообще не слышал ничего о GraphQL и Hasura, каюсь), поэтому статья не претендует на глубокое погружение в тему и нацелена скорее на аналитиков и тестировщиков, которые не работали с упомянутыми инструментами.

Теперь всё, переходим к контенту с чистой совестью.

---

Что такое GraphQL?

По данным https://graphql.org/, GraphQL — это язык запросов к API и open-source среда для их выполнения. Изначально разработан Facebook как внутренний проект, внешний stable-релиз значится июнем 2018 года.

Язык GraphQL позволяет отправлять HTTP-запросы и получать на них ответы в виде объектов JSON. Тут есть важное уточнение, что все типы запросов GraphQL отправляются через POST. При этом есть следующие типы запросов:

• query (аналог GET в REST);

• mutation (аналог POST и PUT в REST);

• subscription.

Подробнее мы рассмотрим сигнатуры запросов query и mutation далее в практическом блоке.

Как заверяет сайт GraphQL, GraphQL может использоваться с любым backend-фреймворком или языком программирования. Логично предположить, что в таком случае для запросов используется какая-то универсальная система типов самого GraphQL. Так и есть: у GraphQL своя система типов, которая позволяет описывать схемы API в синтаксе Schema Definition Language (SDL).

Схема в GraphQL описывает, как клиент может запросить или изменить данные, например, какие поля можно выбирать, в каком формате должен быть запрос и т. д. На мой взгляд, вопрос описания схем для GraphQL и проведение валидации запросов по ним крайне интересен и для аналитиков, и для тестировщиков, однако так как это не предмет данной статьи, подробно останавливаться на этом не буду. Правила и ключевые аспекты типов и схем подробно описаны в спецификации.

Бытует мнение, что GraphQL — это следующий, принципиально новый этап развития API относительно REST.

Поэтому было бы нечестно даже в общем и кратком обзоре упустить такой момент и не рассмотреть GraphQL в сравнении с более знакомым RESTful API.

Что-то похоже на RESTful API… А в чем отличия?

Кажется, этим вопросом много кто задавался (например, тут: 1, 2 и 3).

Да и вообще на собеседованиях аналитиков вопрос: «Назовите отличия REST от SOAP», на мой взгляд, задается так часто, что должен уже получить какое-нибудь развитие. Например, «Назовите отличия REST, SOAP и GraphQL друг от друга».

В данной статье я не ставлю перед собой задачу показать сравнение GraphQL с SOAP и остановлюсь на более популярном сравнении GraphQL с REST по чисто личным причинам: с RESTful API мне приходилось больше работать, он явно ближе моему сердцу ?.

Сходства и различия опять-таки буду приводить с пользовательской точки зрения, такие, которые могут быть полезны аналитикам и тестировщикам.

О’кей, мы более-менее разобрались, что такое GraphQL. А как с ним работать?

Основной список сервисов, которые помогают работать с GraphQL, лежит тут. В нем значится и такой инструмент, как Hasura.

Рассмотрим его чуть подробнее.

Что такое Hasura?

Hasura GraphQL Engine — это open-source веб-сервер приложений, который при подключении в БД PostgreSQL дает production-ready GraphQL API.

То есть, например, подключив Hasura к уже существующей БД, к ней сразу же с момента настройки можно будет выполнять запросы GraphQL для получения или изменения данных. Бизнес-логику при этом можно реализовать с помощью триггеров на события, REST APIs, отдельный сервис GraphQL API или же хранимые процедуры.

Для меня как для пользователя, который использует Hasura для тестирования, тут важны две простые вещи:

• через нее можно делать запросы к БД;

• через нее можно выполнять GraphQL-запросы.

Перейдем к практической части: посмотрим, где и как можно выполнять запросы к БД и собственно GraphQL-запросы.

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

Запросы GraphQL можно выполнять в разделе API:

Тут всё просто: выполняем запросы в консоли (там, где у нас закомментировано милое приветствие в GraphQL) и справа получаем результат выполнения запроса.

Доступ к данным подключенной БД получаем в разделе Data. Тут можно просмотреть данные таблиц через графический редактор, отредактировать их, удалить и так далее. Для этого достаточно выбрать нужную таблицу и нужный тип операции (как в знакомых мне pgAdmin, DataGrip и DBeaver, через которые я работала с PostgreSQL).

А еще тут можно выполнять SQL запросы в raw SQL:

Queries

Если нам нужно получить данные, в консоль Hasura (см. картинку выше) можно написать запрос в формате:

{   user {     login   } }

Этим запросом мы получим логин пользователя из подключенной БД, например:

{   "data": {     "user": {       "login": "ivanovmp"     }   } }

Чаще всего, конечно, мы либо запрашиваем данные какой-то конкретной записи, объекта или же массив объектов. Для запроса конкретной записи или записей параметры запроса можем указать так:

{   users(name: "marina", status: "active") {     email     login   } }

Также для запроса можно указать limit и orderby по аналогии с SQL-запросами. Подробнее можно почитать тут и тут.

Результат запроса выше может быть таким:

{   "data": {     "users": [         { "email": "marinaivanova@aaa.ru", "login": "ivanovama" },         { "email": "mar88af@33.ru", "login": "kirinovamp" }     ] } }

Mutations

Этот тип запросов реализует подходы более знакомых из RESTful APIs методов POST и DELETE.

В mutations также можно передавать параметры. Выше был приведен пример с явной передачей параметров, но их можно указать еще и в виде переменных, например, $name и $status из примера выше.

Запрос на удаление может выглядеть так:

mutation deleteUser($filter: UserFilter!) {   deleteUser(filter: $filter) {     user {       email       login     }   } } #### далее привожу значение фильтра, который можно указать {  "filter":   {  "status": "inactive"  } }

В результате операции мы получим список удаленных клиентов:

{   "data":  {     "users": [         { "email": "sdfa@aaa.ru", "login": "sdfa" },         { "email": "pertaf@33.ru", "login": "pertaf" }     ] } }

Запрос на изменение, который в RESTful API мы могли бы передать через POST, в GraphQL тоже выполним через mutation c указанием параметров:

mutation {          updateUser ( userId:1, email: "merkuloba@pp.com", login: "merkulovba")          ##устанавливаем для пользователя 1 email и login из параметров          {             id             email             login          } }

В результате запроса получим измененные данные пользователя:

{   "data": {     {       "id": 1,       "email": "merkuloba@pp.com",       "login": "merkulovba"     } }

Заключение

В статье мы рассмотрели GraphQL API в сравнении с, возможно, более знакомым RESTful API и немного узнали о том, как использовать консоль Hasura при работе с GraphQL API.

По некоторым данным, только за последний год использование проекта GraphQL выросло на 60%:

Проект растет и развивается, что подтверждается и активностью проекта на гите. На примере репозитория с документацией:

Поэтому надеюсь, что начальное представление о GraphQL и Hasura, которое дала эта статья, вам еще пригодится и станет только отправной точкой в вашей работе с этими инструментами.