Налаштування 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 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.