REST vs GraphQL: как выбрать API

REST и GraphQL — два подхода к построению веб-API. REST — стандарт 2000-х, GraphQL — продукт Facebook 2012 года, опубликован в 2015. Разница принципиальная.

REST

Representational State Transfer. Рой Филдинг, 2000. Архитектурный стиль на основе HTTP.

• Ресурсы имеют URL: /users/123
• Методы HTTP: GET, POST, PUT, DELETE
• Один URL — один тип ресурса
• Stateless
• Кэширование встроено через HTTP

Пример REST

GET /users/123
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "address": {...},
  "preferences": {...}
}

Чтобы получить список постов пользователя:

GET /users/123/posts

Проблемы REST

• Over-fetching: получаем больше данных, чем нужно
• Under-fetching: один экран требует N запросов к разным ресурсам
• Версионирование API: v1, v2, v3 — сложно
• Поддержка меняется — то добавляем поля, то убираем

GraphQL

Язык запросов для API. Клиент точно описывает, что хочет получить.

query {
  user(id: 123) {
    name
    posts(last: 5) {
      title
    }
  }
}

Ответ:

{
  "data": {
    "user": {
      "name": "Alice",
      "posts": [{"title": "..."}, ...]
    }
  }
}

Плюсы GraphQL

• Клиент получает ровно то, что нужно
• Один запрос вместо нескольких
• Строгая типизация (schema)
• Интроспекция: автодокументация
• Эволюция API без версий (добавлять поля — не ломает старых клиентов)

Минусы GraphQL

• Кэширование сложнее (HTTP-кэш не работает)
• Rate limiting сложнее (один запрос может быть тяжёлым)
• N+1 проблема: без DataLoader можно сделать множество запросов к БД
• Все запросы POST — нет различия по семантике
• Новый слой сложности на сервере
• Обучение команды

Когда REST лучше

• Простое CRUD-приложение
• Сильная зависимость от HTTP-кэширования
• Публичный API с множеством разных клиентов
• Ресурсы хорошо декомпозируются
• Команда привычна к REST

Когда GraphQL лучше

• Множество разных клиентов (iOS, Android, web) с разными нуждами
• Сложные связи между ресурсами
• Быстро меняющиеся требования UI
• Microservices с API Gateway
• Real-time через subscriptions

GraphQL в продакшене

• Facebook: всё на GraphQL
• GitHub: v4 API
• Shopify: в документации
• Netflix, Twitter, Airbnb используют
• Российские: Ozon, Авито в определённых частях

Альтернативы

• gRPC: Google, бинарный протокол, быстрый
• tRPC: полная типизация от клиента до сервера в TypeScript
• SOAP: старый XML-протокол, ещё жив в enterprise
• OData: Microsoft, для enterprise

BFF

Backend for Frontend. Специальный API для конкретного фронта. GraphQL часто используется как BFF: один endpoint, который собирает данные из многих микросервисов.

Комбинации

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

Инструменты

• GraphQL: Apollo, Relay, urql (клиенты), Apollo Server, Hasura, Prisma (серверы)
• REST: OpenAPI/Swagger, Postman, FastAPI, Express

Обучение

• REST: понятно за час, мастерство — недели
• GraphQL: понятно за день, N+1 и авторизация — подводные камни месяцами
• Не надо начинать с GraphQL, если REST ещё не освоен