GraphQL vs REST: руководство по выбору дизайна API

Что такое REST API?

REST (Representational State Transfer) — архитектурный стиль API, построенный на протоколе HTTP. Ресурсы идентифицируются по URI.

Каждый эндпоинт представляет конкретный ресурс или коллекцию: GET /users, GET /users/123, POST /users.

CRUD-операции выполняются с помощью HTTP-методов (GET, POST, PUT, DELETE). Формат ответа обычно JSON.

REST основан на принципах stateless, cacheable и uniform interface. Использует все возможности HTTP (кэширование, коды статуса).

Что такое GraphQL?

GraphQL — это язык запросов и runtime, разработанный Facebook. Клиент запрашивает именно те данные, которые ему нужны.

Единый эндпоинт: /graphql. Клиент указывает, какие поля он хочет в запросе. Сервер возвращает только запрошенные поля.

Schema: система типов API. Модель данных определяется с помощью type definitions. Типы Query, Mutation и Subscription.

Resolver: функции, которые обращаются к источнику данных для каждого поля. Данные могут быть получены из базы данных, REST API, микросервиса и т.д.

Сравнение: преимущества и недостатки

Over-fetching/Under-fetching: REST возвращает ненужные данные (over-fetching) или недостаточные данные (under-fetching). GraphQL возвращает именно запрошенные данные.

Единый запрос: с помощью GraphQL можно получить несколько ресурсов в одном запросе. С REST нужны несколько запросов.

Кэширование: REST естественно поддерживает HTTP-кэширование (Cache-Control, ETag). Кэширование в GraphQL более сложное (persisted queries, Apollo cache).

Кривая обучения: REST изучается с знанием HTTP. GraphQL требует новых концепций, таких как schema, resolver, query language.

Tooling: Postman, Swagger для REST. GraphiQL, Apollo Studio для GraphQL. Оба имеют хорошие экосистемы инструментов.

Случаи использования

Предпочитайте REST: простые CRUD API, публичные API, когда кэширование важно, когда bandwidth ограничен для мобильных приложений.

Предпочитайте GraphQL: сложные требования к данным, несколько фронтендов (web, mobile, desktop), агрегация микросервисов, подписки в реальном времени.

Гибридный подход: REST для публичного API, GraphQL для внутреннего/federation. Некоторые компании используют оба вместе.

BFF (Backend for Frontend): отдельный GraphQL-слой для каждого фронтенда. Разные запросы для web и mobile.

Сравнение производительности

REST: HTTP-кэширование, поддержка CDN, простой load balancing. Каждый эндпоинт может кэшироваться независимо.

GraphQL: проблема N+1 (решается с помощью DataLoader), анализ сложности запросов, кэширование с persisted queries.

Bandwidth: GraphQL предотвращает ненужный трансфер данных. Обеспечивает экономию bandwidth для мобильных приложений.

Латентность: REST может требовать несколько round-trip. GraphQL получает все данные в одном запросе. Однако сложные запросы могут быть медленными на стороне сервера.

Критерии выбора

Опыт команды: REST более распространён и известен. GraphQL требует больше обучения.

Потребители API: REST для публичного API (большая совместимость). GraphQL для внутреннего API (больше гибкости).

Сложность данных: REST для простых моделей данных. GraphQL для сложных, связанных моделей данных.

Требование кэширования: REST для интенсивного кэширования. GraphQL subscriptions для данных в реальном времени.

Миграция: оберните существующий REST API с помощью GraphQL (schema stitching, federation). Выполняйте постепенный переход.