GraphQL 10 лет. Пора в нем разобраться?

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

Что такое GraphQL?

GraphQL — это язык запросов к API и среда выполнения, разработанный Facebook в 2012 году и опубликованная как open source в 2015 году. Основное преимущество GraphQL заключается в том, что он предоставляет клиенту возможность запрашивать только те данные, которые ему необходимы, и в удобной структуре.

На изображении ниже показан, простой пример GraphQL query запроса. Запрашиваю страну, где code равен RU, с указанием необходимых полей для получения.

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

• Query - получение данных (аналог GET запроса в REST)

• Mutation - добавление и изменение данных (аналог POST, PUT запроса в REST)

• Subscription - подписка на изменение данных. Но с ними не все так однозначно, подробнее о них написано здесь.

Основные особенности

1. Гибкость запросов: позволяет клиенту запрашивать только те данные, которые ему действительно нужны.

2. Единая точка входа:  есть только один endpoint (обычно /graphql), через который проходят все запросы.

3. Schema definition language (SDN): GraphQL API основывается на схеме, которая описывает все доступные данные, их типы и связи между ними. Подробнее о том, как читать SDL можно почитать в этой статье

4. Поддержка real-time: Subscriptions позволяют подписаться на обновления.

5. Сильная типизация: все данные строго типизированы, что помогает избежать ошибок. Типы включают стандартные (String, Int, Float, Boolean, Enum ) и на их основе можно создавать пользовательские типы данных.

6. Единый источник данных: GraphQL может объединять данные из разных источников (базы данных, REST API, микросервисы и т.д.) в единый API

7. Широкая экосистема инструментов: доступны различные генераторы кода для клиентов, поддерживающие полную спецификацию GraphQL. Одна из ключевых функций — встроенная поддержка кэширования запросов.

И чтобы долго не задерживаться на теории, давайте сразу перейдем к практике и попробуем GraphQL в действии! А если хочется больше теории, на хабре есть для этого статья .

Как быстро поднять свой GraphQL?

Если вы хотите быстро создать свой GraphQL API, есть множество инструментов, которые помогут вам это сделать. Все инструменты я сам использовал в продакшене.

Hasura
Автоматически генерирует GraphQL API поверх вашей базы данных (PostgreSQL), так же позволяет строить федерации - это построение единого шлюза для нескольких сервисов. Сам я на проектах использую версию v2 self-hosted. Быстрый старт

Directus
Это Headless CMS + Backend, накладывает API на существующую базу данных и позволяет быстро создавать админ-панели. Очень простой и удобный инструмент для запуска MVP, что-то большее не довелось сделать на нем. Быстрый старт

Apollo Server
Apollo Server - это сервер GraphQL с открытым исходным кодом, совместимый со спецификациями, который совместим с любым клиентом GraphQL, включая клиента Apollo. Не самый быстрый старт

Публичные API с поддержкой GraphQL

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

1. SpaceX GraphQL API:

2. GitHub API:

3. Gitlab API

4. Rick and Morty API

5. Countries API

Эндпоинты GraphQL схем можно добавить в Sdudio Apollo, указав при необходимости заголовки авторизации.

Как подключить GraphQL к фронту?

Чтобы быстро и удобно подключить GraphQL на клиенте, рекомендую использовать Apollo Client. Также обязательно настройте кодогенерацию — это значительно упростит разработку за счет автоматического создания типов данных, хуков, классов и других вспомогательных структур на основе схемы, и все со строгой типизацией.

Apollo Client поддерживает:

• React и React Native. Также совместим с другими веб-фреймворками, но основная документация сосредоточена на React.

• iOS.

• Kotlin.

Для Flutter рекомендую использовать graphql_flutter и graphql_codegen.

Как изменится GraphQL в 2025 году?

1. Обязательная поддержка application/graphql-response+json:
   

   • С 1 января 2025 года серверы обязаны поддерживать медиа-тип application/graphql-response+json для ответов на запросы, которые указывают этот тип в заголовке Accept.

   • Это изменение направлено на улучшение совместимости и надежности, так как application/graphql-response+json лучше подходит для обработки ошибок и частичных ответов в GraphQL.

2. Кодировка UTF-8:
   

   • Ответы, использующие application/graphql-response+json, должны быть закодированы в UTF-8.

3. Изменение поведения по умолчанию:
   

   • Если клиент не указывает заголовок Accept, сервер должен рассматривать запрос как если бы он содержал Accept: application/graphql-response+json. Это изменение направлено на постепенный отход от использования application/json для ответов GraphQL.

4. Статус коды:

   • При использовании application/graphql-response+json сервер должен возвращать соответствующие статус-коды HTTP (например, 4xx или 5xx) в случае ошибок, которые полностью препятствуют генерации корректного GraphQL-ответа. Это отличается от текущей практики, где серверы могут возвращать 200 OK даже при ошибках.

5. Легаси-совместимость:
   

   • До 2025 года клиентам рекомендуется включать application/json в заголовок Acceptдля обеспечения совместимости с устаревшими серверами. После 2025 года это больше не будет необходимо.

Источник1 Источник2

В итоге это означает, что мем о некорректных статусных кодах GraphQL потеряет актуальность, и это отличная новость!