Как настроить HTTP-кэширование API: ETag, Last-Modified, Vary

Отметим: когда API возвращает 200 с полным телом на каждый запрос, это бесполезно тратит трафик и нагружает сервер. Мы настраиваем HTTP-кэширование так, чтобы клиенты и CDN кэшировали ответы, а сервер отвечал 304 Not Modified, если данные не изменились. За 7 лет мы внедрили эту стратегию в 50+ проектах — снижали трафик до 90% и ускоряли средний ответ на 50%. Это позволяет сократить расходы на инфраструктуру до 70%. Типичная экономия на инфраструктуре для проектов с 10 000+ запросов в час составляет от 100 000 рублей в месяц.

Проблемы, которые решаем

Проблема 1: Отсутствие ETag — клиент не может сделать условный запрос. Каждый запрос возвращает полное тело, даже если данные не менялись. Решение: вычисляем хеш по updated_at и id (для единичных ресурсов) или по максимальному updated_at + количество записей (для коллекций). ETag точнее Last-Modified, так как реагирует на любые изменения, а не только на время.

Проблема 2: Неправильный Vary — CDN кэширует ответ для одного языка или сжатия и отдаёт всем. Например, если Vary не содержит Accept-Language, русский пользователь может получить английскую версию. Решение: указываем все заголовки, влияющие на представление.

Проблема 3: «Мёртвый» Cache-Control — no-cache без ETag — клиент не кэширует вообще. Оптимальная комбинация: Cache-Control: public, max-age=60, s-maxage=300 + ETag.

Как мы это делаем: стек и кейс

Используем Laravel 11 на PHP 8.3, PostgreSQL, Redis. Для каждого эндпоинта API определяем стратегию кэширования:

• Единичные ресурсы — ETag на основе updated_at + id. Если If-None-Match совпадает — 304.
• Коллекции — ETag по максимальному updated_at и количеству записей с учётом пагинации.
• Мультиязычные — Vary: Accept-Language, ETag включает код языка.

Пример из реального проекта: каталог товаров с 50 000 позиций, 10 языков. После настройки ETag + Vary трафик на CDN снизился с 200 ГБ/мес до 30 ГБ/мес (на 85%), а среднее время ответа упало с 800 мс до 150 мс для кэшированных запросов. Средняя экономия на CDN-трафике составила 120 000 рублей в месяц. Если хотите получить аналогичный результат, закажите аудит кэширования вашего API.

Почему ETag эффективнее Last-Modified?

Last-Modified имеет точность до секунды — если обновления происходят чаще, возможны коллизии. ETag учитывает само содержимое, поэтому детектирует любые изменения, включая перезапись тех же данных (если хеш считается по содержимому). Для JSON API мы используем хеш от updated_at и id — он дёшев и достаточно уникален.

Настройка Vary для мультиязычного API

Укажите в ответе Vary: Accept-Language, Accept-Encoding. Для CORS с разными origin — Origin. Избегайте Vary: Authorization — каждый токен создаёт отдельную запись в кэше CDN. Если нужна авторизация, используйте приватное кэширование (private, max-age=0, must-revalidate) и ETag.

Как инвалидировать кэш на CDN?

Используйте теги (Cache-Tag) или суррогатные ключи. При обновлении ресурса отправляете запрос на purge по тегу. Cloudflare и Fastly поддерживают массовую инвалидацию одним вызовом API. Экономия на CDN-трафике может достигать 90%, что снижает затраты на хостинг.

Директивы Cache-Control

public function handle($request, Closure $next)
{
    $response = $next($request);
    if ($response->isSuccessful()) {
        $etag = md5($response->getContent());
        $response->setEtag($etag);
        $response->setLastModified($response->getDate());
        if ($response->isNotModified($request)) {
            return response()->noContent(304);
        }
    }
    return $response;
}

Процесс работы

1. Аналитика — аудит текущих заголовков, выявление узких мест.
2. Проектирование — выбор стратегии для каждого эндпоинта (сильное/условное кэширование).
3. Реализация — добавление ETag, Last-Modified, Vary в middleware или контроллеры.
4. Тестирование — проверка кодов ответа, заголовков, поведения CDN.
5. Деплой — настройка инвалидации (суррогатные ключи, purge API).

Сроки ориентировочно

Стоимость рассчитывается индивидуально после анализа вашего API.

Что входит в работу

• Реализация ETag / Last-Modified для всех эндпоинтов
• Настройка Cache-Control и Vary по типам ресурсов
• Интеграция с CDN (Cloudflare, Fastly)
• Система инвалидации кэша (суррогатные ключи или purge API)
• Документация по стратегии кэширования
• Пост-релизная поддержка в течение 2 недель

Итог

Правильное HTTP-кэширование — дешёвый способ радикально снизить нагрузку. Мы гарантируем, что после настройки вы увидите падение трафика и ускорение ответов. Получите консультацию по настройке кэширования вашего API — мы оценим текущую ситуацию и предложим оптимальную стратегию.

RFC 7232

Разработка API: REST, GraphQL, WebSocket, tRPC

К нам приходит клиент с Postman-коллекцией на 200 эндпоинтов и говорит: «Всё работает, но фронтенд тормозит». Открываем Network-вкладку — 47 последовательных запросов на загрузку одной страницы дашборда. Каждый ждёт предыдущего. Это не проблема скорости сервера — это проблема архитектуры API. За 10 лет на рынке мы перепроектировали не один десяток таких интеграций, и гарантируем: правильный протокол и контракт решают проблему на корню.

Когда 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 — экономия трафика составила 92%. Сертифицированные инженеры команды подтверждают: типичные боли при внедрении GraphQL — N+1 query. Резолвер для поля author у поста вызывает SELECT * FROM users WHERE id = ? для каждого поста в списке. На странице с 20 постами — 21 запрос к базе. Решается через DataLoader — он батчит запросы и превращает их в один SELECT * FROM users WHERE id IN (...).

Что такое tRPC и чем он лучше REST/GraphQL?

Если весь стек на TypeScript (Next.js + Node/Bun), tRPC убирает целый слой проблем. Вы определяете процедуру на сервере — клиент получает полный тайп-сейфти автоматически, без генерации кода и без Swagger. Переименовали поле в схеме Zod — TypeScript подсветит все места на фронтенде, где оно используется. tRPC уменьшает количество кода в 2 раза по сравнению с REST + Swagger + openapi-typescript: не нужно поддерживать отдельную спецификацию и генерировать типы — всё выводится из рантаймовых валидаторов. Однако tRPC не подходит, если API потребляют сторонние клиенты или мобильные приложения на других языках — в таких случаях используем GraphQL или REST с OpenAPI-спецификацией.

WebSocket и реальное время: когда SSE, когда WS?

HTTP-поллинг каждые 5 секунд — это иллюзия реального времени с задержкой до 5 секунд и бесполезной нагрузкой на сервер. Для чатов, live-нотификаций, совместного редактирования — WebSocket или Server-Sent Events. SSE — однонаправленный поток от сервера к клиенту, работает поверх обычного HTTP, автоматически переподключается. Подходит для нотификаций, стриминга данных, прогресс-баров. WebSocket — двунаправленный, нужен для чатов и коллаборативных фич. Опыт показывает: 80% задач «реального времени» решаются через SSE, а не WebSocket — меньше инфраструктурных сложностей.

Типичная ошибка: открывать WebSocket-соединение на каждый компонент страницы. На одном проекте дашборд открывал 12 параллельных WS-соединений. Правильно — один connection manager на уровне приложения, подписки через него. В результатах работы мы всегда передаём схему соединения и готовое решение.

Swagger / OpenAPI как контракт

Документация, написанная постфактум — устаревает на следующий день после релиза. Мы пишем спецификацию OpenAPI 3.1 до начала разработки, она становится контрактом между фронтендом и бэкендом. Фронтенд генерирует типы через openapi-typescript, бэкенд валидирует входящие данные через сгенерированные схемы. Расхождение контракта с реализацией ловится на CI, а не на ревью. Для Laravel — l5-swagger или dedoc/scramble. Для 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 без версионирования ломают клиентов. Три подхода мы используем в проектах:

Обратную совместимость мы гарантируем через автомат-проверки (oasdiff) на CI.

Как мы разрабатываем API: пошаговый план

1. Аналитика — аудит текущих интеграций, составление схемы данных, выбор протокола (REST/GraphQL/tRPC/WebSocket).
2. Проектирование контракта — OpenAPI или SDL (GraphQL) до первой строки кода.
3. Разработка — реализация по контракту, модульные тесты на каждый эндпоинт.
4. Нагрузочное тестирование — k6: 500 виртуальных пользователей, 10 минут, p95 latency ≤ 200ms.
5. Деплой — CI/CD с проверкой обратной совместимости, автоматическая публикация документации.
6. Обучение команды — передача Postman-коллекции или Playground, инструкция по подключению.

Что входит в работу (deliverables)

• OpenAPI 3.1 спецификация (или SDL для GraphQL).
• Сгенерированные клиентские типы для TypeScript / Dart / Kotlin.
• Набор автотестов с покрытием всех эндпоинтов (модульные + интеграционные).
• Нагрузочные тесты (k6) и отчёт (p50/p95/p99 latency, RPS).
• Документация в Swagger UI / Redoc / GraphiQL.
• Обучение команды (2–4 часа воркшопа).
• Поддержка в течение 30 дней после сдачи (по договору).

Наш опыт

• 10+ лет на рынке разработки API.
• 200+ завершённых проектов (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифицированных инженеров (AWS, Kubernetes, API Design).
• Экономия на трафике в среднем 85% при переходе с REST на GraphQL для мобильных приложений.
• 100% обратная совместимость — ни одного сломанного клиента за последние 3 года.

Сроки

Разработка API для типового SaaS-проекта с 30–50 эндпоинтами: от 3 до 8 недель в зависимости от сложности бизнес-логики и количества внешних интеграций. Миграция существующего REST API на GraphQL — от 2 до 6 недель. Добавление WebSocket-слоя к готовому бэкенду — от 1 до 3 недель. Стоимость рассчитывается индивидуально после аудита. Получите консультацию — свяжитесь с нами, чтобы обсудить ваш проект.