Кратко и по существу — принципы RESTful и как он соотносится с GraphQL и gRPC; когда что выбрать.
Основные принципы проектирования RESTful API
- Ресурсо-ориентированность: моделируйте сущности как ресурсы с понятными URI (например, `/users`, `/orders/123`), используйте существительные, множественное число для коллекций.
- Унифицированный интерфейс через HTTP-методы: GET — чтение, POST — создание, PUT — полная замена, PATCH — частичное обновление, DELETE — удаление.
- Статeless: сервер не хранит состояние клиента между запросами; все данные контекста передаются в запросе.
- Использование кодов состояния HTTP для семантики ошибок и результата (2xx, 4xx, 5xx).
- Представления и контент-нейготоация: поддержка JSON, XML и т. п.; заголовки `Accept`/`Content-Type`.
- Кеширование: явное управление кэшированием через заголовки (`Cache-Control`, `ETag`) для CDN/прокси.
- Идемпотентность и безопасные операции: документируйте какие методы идемпотентны.
- Версионирование: URI (`/v1/...`) или заголовки для совместимости при изменениях.
- Пагинация, фильтрация, сортировка и поля(проекции) для ограничений выдачи (`?page=`, `?limit=`, `?fields=`).
- Документация и контракт (OpenAPI/Swagger) для удобства потребителей.
- Аутентификация/авторизация (OAuth2, JWT), лимиты (rate-limiting), обработка ошибок в едином формате.
Плюсы REST
- Простота, знакомость, широкая поддержка в браузерах, easy to debug (текстовый JSON).
- Хорош для кеширования и CDN.
- Подходит для публичных API и взаимодействия с веб/мобильными клиентами.
- Лёгкая эволюция в рамках совместимых расширений.
Минусы REST
- Возможна избыточная или недостаточная выдача данных (over/under-fetching).
- Дуальное владение семантикой между endpoint’ами и репрезентациями (иногда ведёт к множеству версий).
GraphQL — краткая характеристика
- Клиент задаёт именно ту структуру данных, которую хочет; единый endpoint (обычно `/graphql`) и гибкие селекторы полей.
- Сильная типизация через схему (SDL). Поддержка мутаций и подписок (реактивность).
- Идеален для агрегации данных из нескольких источников и уменьшения количества запросов.
- Инструменты: схема как контракт, автогенерация типов на клиенте.
Плюсы GraphQL
- Минимизирует over/under-fetching; клиент-ориентированный API.
- Один endpoint, мощные возможности для фронтенда (мобильные/SPA).
- Хорош для быстрой итерации UI при частых изменениях требований.
Минусы GraphQL
- Сложнее кеширование через CDN и HTTP кеш; сложнее оптимизировать на уровне HTTP.
- Нагрузка на бэкенд при сложных вложенных запросах; проблемы N+1 (решаются DataLoader/батчингом).
- Более сложная авторизация на уровне полей; более высокий порог входа.
- Тяжелее логировать и мониторить из-за единого endpoint.
gRPC — краткая характеристика
- RPC-фреймворк по HTTP/2 с бинарной сериализацией Protobuf; генерируемые клиентские/серверные контракты.
- Поддержка unary, серверных/клиентских/двунаправленных стримов.
- Сильная типизация, компактная сериализация, эффективные двоичные передачи.
Плюсы gRPC
- Очень высокая производительность и низкая латентность (HTTP/2, бинарный протокол).
- Отлично для внутреннего взаимодействия микросервисов, real-time и стриминга.
- Автогенерация кода и контрактов для многих языков.
Минусы gRPC
- Плохая нативная поддержка в браузере (нужен прокси/HTTP-gateway).
- Бинарный трафик сложнее отлаживать и кешировать CDNs.
- Меньшая гибкость для неструктурированных/эволюционирующих клиентских требований (надо менять протокол/протофайлы).
Когда что предпочтительнее
- REST предпочтителен:
- Публичные HTTP API для сторонних клиентов, где простота, совместимость и кеширование важны.
- Когда нужно легко тестировать и отлаживать через браузер/curl.
- Когда важна совместимость с CDN/proxy.
- GraphQL предпочтителен:
- Клиенты с разными требованиями к данным (мобильные, SPA) — чтобы избежать множества запросов.
- Когда фронтенд-ориентированная разработка требует гибкой схемы выборки данных.
- Когда нужно агрегировать данные из нескольких источников в один запрос.
- gRPC предпочтителен:
- Внутренние микросервисы, требующие высокой пропускной способности и низкой латентности.
- Сценарии с потоковой передачей данных (стриминг) и двунаправленным взаимодействием.
- Когда важны строго типизированные контракты и автогенерация кода.
Практика: смешанные подходы
- Часто используют комбинации: gRPC внутри инфраструктуры для быстрого взаимодействия, REST/GraphQL — наружный API для клиентов; или gRPC + gRPC-Gateway для автоматической экспозиции REST.
- GraphQL может сидеть поверх нескольких REST/gRPC источников и выступать фасадом под требования UI.
Критерии выбора (быстрое правило)
- Нужна простота и совместимость → REST.
- Нужна гибкая выдача данных под фронт → GraphQL.
- Нужна производительность, стриминг и типизация в межсервисной связи → gRPC.
Если нужно, могу кратко перечислить конкретные best-practices для REST (наименование ресурсов, версии, пагинация, ETag, PATCH, коды ошибок).