GraphQL: основные понятия

GraphQL — это язык запросов и серверная среда для API с открытым исходным кодом. Он был специально создан как альтернатива REST API, чтобы избежать с одной стороны избыточности данных, а с другой их недостатка.

Главная фишка GraphQL: клиент может получить все нужные данные одним запросом к одному эндпоинту, даже если они будут располагаться в разных источниках. При этом структуру ответа определяет сам потребитель.

Принцип работы

По сути GraphQL выполняет роль оркестратора – переадресовывает фрагменты запроса на разные сервисы. GraphQL умеет отправлять данные поверх HTTP-протокола, Websocket и SSH.

В GraphQL есть всего два вида запросов:

1. query – запросы на чтение данных (используется метод GET в HTTP)
2. mutation – запросы на изменение данных (используется метод POST в HTTP)

То есть, если рассматривать акроним CRUD, то query – это R, а mutation – это CUD.

Все запросы клиенты отправляют на одну конечную точку: GraphQL-сервер. Он представляет собой обычный HTTP-сервер, к которому присоединена GraphQL-схема. GraphQL-схема аналогична понятию “контракт” в REST API: схема определяет, какие операции клиент может выполнить в API и определяет, какие типы данных будут использоваться.

GraphQL имеет строгую типизацию. Типы бывают следующие:

• Объектные – сущности с вложенными полями и другими сущностями
• Скалярные – могут содержать только одно атомарное значение. К ним относятся:
  • Int (целочисленные) — 32-битное целое число со знаком
  • Float — число двойной точности с плавающей точкой со знаком
  • String — строка, закодированная в UTF-8
  • Boolean (булевы) — логический тип (true или false)

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

query {
  user(id: 123) {
    name
    email
    age
  }
}

Пример ответа

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "johndoe@example.com",
      "age": 30
    }
  }
}

Ограничения

• Сложность. Для небольших простых приложений настройка таких запросов может показаться слишком сложной и ненужной. В этой ситуации легко можно обойтись классическим REST-подходом.
• Нет кеширования. GraphQL использует всего одну конечную точку, что не позволяет следовать спецификации HTTP-кеширования. Это очень важно, так как кеширование уменьшает объем трафика.
• GraphQL обычно возвращает статус 200 OK даже с ошибкой, но при использовании специальных клиентов эта проблема легко решается.
• Трудности обеспечения безопасности с учётом всех возможных вариантов запросов.

Применение GraphQL

1. GraphQL API хорошо подходит для приложений с большим количеством клиентов и/или источников данных, когда нужно реализовать единообразие в средствах выполнения запросов, уменьшить число конечных точек и снизить нагрузку на сеть.
2. GraphQL отлично подходит для баз с большим количеством записей, позволяя устранить избыточную выборку результатов и получать только нужные данные, чтобы повысить производительность приложения.
3. Когда нет четкого понимания, как клиент использует API, без необходимости заранее определять строгий контракт: можно постепенно создавать API на основе отзывов клиентов.

Официальная документация

GraphQL Documentation

Статьи (теория)

1. Что такое GraphQL — статья от ListenIT + видео-версия
2. Подробности о GraphQL: что, как и почему — статья от RUVDS
3. The complete GraphQL Security Guide — про безопасность на EN
4. Начало работы с безопасностью GraphQL — про безопасность на RU

Статьи (практика)

1. Проектируем GraphQL API в микросервисной архитектуре — опыт от Звука
2. Как и для чего мы два раза переезжали на GraphQL — опыт Яндекс.Афиши
3. GraphQL: от восторга до разочарования
4. Что не так с GraphQL — взгляд разработчика
5. Знакомство с GraphQL — примеры запросов к своей БД в облаке Hasura

Видео и вебинары

1. GraphQL — проектируем интеграцию систем — Анна Овзяк
2. А нужен ли нам GraphQL? — Павел Черторогов
3. Все о GraphQL за 30 минут — от разработчика
4. Про безопасность GraphQL

Открытое API GraphQL

1. API GitHub — документация + попробовать онлайн
2. API Space X — попробовать онлайн