Разработка API: REST, GraphQL, WebSocket, tRPC
Клиент приходит с Postman-коллекцией на 200 эндпоинтов и говорит: «Всё работает, но фронтенд тормозит». Открываешь Network-вкладку — 47 последовательных запросов на загрузку одной страницы дашборда. Каждый ждёт предыдущего. Это не проблема скорости сервера, это проблема архитектуры API.
Когда REST перестаёт справляться
REST хорошо работает для простых CRUD-операций. Но как только у вас появляется мобильное приложение рядом с веб-интерфейсом, начинается over-fetching: мобилка запрашивает /api/users/123 и получает объект на 4KB, хотя ей нужны только name и avatar. Умножьте на список из 50 пользователей — 200KB трафика вместо 8KB.
GraphQL решает это через selection sets. Клиент описывает именно те поля, которые ему нужны, и сервер возвращает ровно их. На проекте с React Native + Next.js мы переехали с REST на Apollo Server: размер payload на главном экране приложения упал с 340KB до 28KB без каких-либо изменений на бэкенде по логике — только схема и резолверы.
Типичные боли при внедрении GraphQL: N+1 query. Резолвер для поля author у поста вызывает SELECT * FROM users WHERE id = ? для каждого поста в списке. На странице с 20 постами — 21 запрос к базе. Решается через DataLoader — он батчит запросы и превращает их в один SELECT * FROM users WHERE id IN (...).
tRPC: когда фронтенд и бэкенд на TypeScript
Если весь стек на TypeScript (Next.js + Node/Bun), tRPC убирает целый слой проблем. Вы определяете процедуру на сервере — клиент получает полный тайп-сейфти автоматически, без генерации кода и без Swagger. Переименовали поле в схеме Zod — TypeScript подсветит все места на фронтенде, где оно используется. Это не магия, это просто типы через границу HTTP.
tRPC не подходит, если API потребляют сторонние клиенты или мобильные приложения на других языках. В таких случаях GraphQL или REST с OpenAPI-спецификацией.
WebSocket и реальное время
HTTP-поллинг каждые 5 секунд — это не реальное время. Это иллюзия реального времени с задержкой до 5 секунд и бесполезной нагрузкой на сервер. Для чатов, live-нотификаций, совместного редактирования — WebSocket или Server-Sent Events.
SSE vs WebSocket: SSE — однонаправленный поток от сервера к клиенту, работает поверх обычного HTTP, автоматически переподключается. Подходит для нотификаций, стриминга данных, прогресс-баров долгих операций. WebSocket — двунаправленный, нужен для чатов и коллаборативных фич. На практике 80% задач «реального времени» решаются через SSE, а не WebSocket — меньше инфраструктурных сложностей.
Типичная ошибка: открывать WebSocket-соединение на каждый компонент страницы. Видели проект, где на дашборде открывалось 12 параллельных WS-соединений. Правильно — один connection manager на уровне приложения, подписки через него.
Swagger / OpenAPI как контракт
Документация, написанная постфактум — устаревает на следующий день после релиза. Мы пишем спецификацию OpenAPI 3.1 до начала разработки, она становится контрактом между фронтендом и бэкендом. Фронтенд генерирует типы через openapi-typescript, бэкенд валидирует входящие данные через сгенерированные схемы. Расхождение контракта с реализацией ловится на CI, а не на ревью.
Для Laravel — l5-swagger или dedoc/scramble (автогенерация из PHP-аннотаций и FormRequest). Для Node.js — @fastify/swagger или Zod + zod-to-openapi.
Аутентификация API
JWT с долгоживущими access-токенами без ротации — источник проблем при компрометации. Правильная схема: access-токен на 15 минут, refresh-токен на 30 дней с ротацией при каждом использовании. Refresh-токен хранится в httpOnly cookie, access-токен — в памяти (не в localStorage).
Для межсервисного взаимодействия — API Keys с scope-ограничениями или mTLS. OAuth 2.0 с PKCE для публичных клиентов (SPA, мобилки).
Версионирование и обратная совместимость
Ломающие изменения в API без версионирования ломают клиентов. Три подхода: URL-версионирование (/api/v2/), заголовок (Accept: application/vnd.api+json;version=2), эволюционное версионирование через добавление полей без удаления старых. Последнее работает для GraphQL — deprecated-директива позволяет постепенно выводить поля из использования.
Процесс работы
Аналитика начинается с аудита текущих интеграций и составления схемы данных. Проектируем API-контракт в OpenAPI или SDL (для GraphQL) — до первой строки кода. Разработка идёт по контракту с автотестами на каждый эндпоинт. Нагрузочное тестирование через k6 перед деплоем: базовый сценарий — 500 виртуальных пользователей, 10 минут, p95 latency не выше 200ms.
Деплой через CI/CD с обязательной проверкой обратной совместимости (oasdiff для OpenAPI). Документация публикуется автоматически из спецификации.
Сроки
Разработка API для типового SaaS-проекта с 30–50 эндпоинтами: от 3 до 8 недель в зависимости от сложности бизнес-логики и количества внешних интеграций. Миграция существующего REST API на GraphQL — от 2 до 6 недель. Добавление WebSocket-слоя к готовому бэкенду — от 1 до 3 недель.