Безпека API, кешування та інтернаціоналізація

1. TLS: перше правило безпеки

TLS (Transport Layer Security) — це протокол шифрування, що захищає дані під час передачі. Для API це означає: завжди https://, ніколи http://.

Навіщо потрібен TLS

Без TLS дані між клієнтом і сервером передаються відкритим текстом. Будь-хто, хто «сидить» між ними (провайдер, публічна Wi-Fi мережа, зловмисник), може:

TLS шифрує весь трафік між клієнтом і сервером. Навіть якщо зловмисник перехопить пакети — він побачить лише шифрований потік байтів.

2. UUID замість послідовних ID

Проблема послідовних ID

Якщо ваш API використовує послідовні числові ідентифікатори (/v1/orders/42, /v1/orders/43), зловмисник може:

1. Перебрати ID — запитати /v1/orders/1, /v1/orders/2, ..., /v1/orders/100000 і зібрати всі дані
2. Оцінити масштаб — якщо останнє замовлення має ID 50 000, зловмисник знає, що у вас ~50 000 замовлень
3. Вгадати ресурс — якщо створив замовлення #42, то замовлення #41 належить іншому користувачу

UUID як рішення

UUID (Universally Unique Identifier) — 128-бітний ідентифікатор, що генерується випадково:

/v1/orders/550e8400-e29b-41d4-a716-446655440000

UUID неможливо перебрати (простір 2¹²⁸ ≈ 3.4 × 10³⁸ варіантів) і він не розкриває інформацію про кількість записів або порядок створення.

app.MapPost("/v1/orders", (OrderRequest req) =>
{
    var order = new Order
    {
        // UUID замість auto-increment
        Id = Guid.NewGuid(),
        Recipe = req.Recipe,
        CreatedAt = DateTime.UtcNow
    };
    
    db.Save(order);
    return Results.Created(
        $"/v1/orders/{order.Id}", order);
});

3. JWT: безпека на практиці

Ми вже розглядали JWT як механізм stateless-авторизації у статті 05. Тепер зосередимось на безпекових аспектах.

Що зберігати в JWT

JWT-токен — це не сховище даних. Він підписаний, але не зашифрований — будь-хто може декодувати його через Base64. Тому:

Час життя токена

Чим коротший час життя токена — тим безпечніше, але і менш зручно для користувача:

Чому два токени? Access token — короткоживучий, бо він передається у кожному запиті (більший ризик перехоплення). Refresh token — довгоживучий, використовується рідко (тільки для оновлення), і його можна відкликати на сервері.

Що робити при компрометації

Якщо access token викрадено, зловмисник може використовувати його до закінчення терміну дії. Зменшити ризик:

1. Короткий час життя — через 15 хвилин токен просто перестане працювати
2. Перевірка IP / fingerprint — токен прив'язаний до клієнта
3. Blacklist — для критичних систем: список відкликаних токенів (порушує stateless, але іноді необхідно)

4. Cache-Control: правильне кешування

Кешування — один із принципів REST, і HTTP надає потужний механізм для його контролю через заголовок Cache-Control.

Два типи кешування

Основні директиви Cache-Control

Стратегії кешування для різних ресурсів

ETag + Cache-Control — комбінований підхід

Найефективніша стратегія кешування — комбінування Cache-Control з ETag:

1. Сервер повертає Cache-Control: max-age=300 і ETag: "v1"
2. Протягом 5 хвилин клієнт використовує локальний кеш (навіть не звертається до сервера)
3. Після 5 хвилин клієнт робить умовний запит з If-None-Match: "v1"
4. Якщо дані не змінились → 304 Not Modified (сервер не передає тіло)
5. Якщо змінились → 200 OK з новими даними і новим ETag

Це дає максимальну ефективність: нема зайвих запитів (перші 5 хвилин), нема зайвих даних (304 після 5 хвилин).

app.MapGet("/v1/recipes", (HttpContext ctx) =>
{
    var recipes = db.GetAllRecipes();
    var etag = $"\"{recipes.GetHashCode()}\"";
    
    // Умовний запит — перевірка ETag
    var ifNoneMatch = ctx.Request.Headers
        .IfNoneMatch.FirstOrDefault();
    if (ifNoneMatch == etag)
        return Results.StatusCode(304);
    
    // Заголовки кешування
    ctx.Response.Headers.ETag = etag;
    ctx.Response.Headers.CacheControl = 
        "public, max-age=3600"; // 1 година
    
    return Results.Ok(recipes);
});

5. Інтернаціоналізація (i18n)

Якщо ваш API обслуговує клієнтів з різних країн, потрібно враховувати мовні та культурні відмінності.

Заголовок Accept-Language

Клієнт повідомляє бажану мову через стандартний HTTP-заголовок:

GET /v1/products/42 HTTP/1.1
Accept-Language: uk-UA, en-US;q=0.5

Це означає: «Я хочу українську (пріоритет 1.0). Якщо немає — англійську (пріоритет 0.5)».

Що локалізувати

Стратегія: контент vs метадані

Є два підходи до локалізації:

{
  "id": 42,
  "name": "Лунго",
  "description": "Подовжений еспресо з м'яким смаком"
}

{
  "id": 42,
  "name": {
    "uk": "Лунго",
    "en": "Lungo",
    "de": "Lungo"
  },
  "description": {
    "uk": "Подовжений еспресо з м'яким смаком",
    "en": "Extended espresso with a mild taste"
  }
}

Часові зони

Окреме джерело проблем — часові зони. Правила:

1. Зберігайте усі дати в UTC на сервері
2. Передавайте дати у форматі ISO 8601 з вказанням зони: "2024-02-26T14:30:00Z" (Z = UTC)
3. Локалізацію часових зон залиште клієнту — мобільний додаток знає часову зону користувача

Ніколи не зберігайте дати у «локальному» часі на сервері. «14:00 у Києві» і «14:00 у Лондоні» — це різні моменти часу. Якщо сервер зберігає лише «14:00» без зони — ніхто не знає, що це означає.

6. Додаткові заходи безпеки

CORS (Cross-Origin Resource Sharing)

Якщо ваш API використовується з браузера (SPA-додатки), потрібно налаштувати CORS — механізм, що контролює, з яких доменів дозволені запити:

builder.Services.AddCors(options =>
{
    options.AddPolicy("api", policy =>
    {
        policy
            // Дозволені домени
            .WithOrigins(
                "https://app.coffee-service.com",
                "https://admin.coffee-service.com")
            // Дозволені методи
            .WithMethods("GET", "POST", "PUT", "DELETE")
            // Дозволені заголовки
            .WithHeaders("Authorization", "Content-Type",
                "If-Match", "If-None-Match")
            // Дозволити cookies/credentials
            .AllowCredentials();
    });
});

app.UseCors("api");

Rate limiting за категоріями

Не всі ендпоінти потребують однакових лімітів:

Заголовки безпеки

app.Use(async (ctx, next) =>
{
    // Заборона відображення сторінки в iframe
    ctx.Response.Headers["X-Frame-Options"] = "DENY";
    
    // Блокувати MIME-sniffing
    ctx.Response.Headers["X-Content-Type-Options"] = 
        "nosniff";
    
    // Суворий TLS
    ctx.Response.Headers
        ["Strict-Transport-Security"] = 
        "max-age=31536000; includeSubDomains";
    
    await next(ctx);
});

7. Практичні завдання

Рівень 1: Базовий

Рівень 2: Проєктування

8. Резюме

Далі: у фінальній статті модуля ми розберемо процес проєктування API — покроковий алгоритм, code style, документування через OpenAPI/Swagger.