Стандарти модуля API

Цей файл перевизначає кореневий CLAUDE.md для всього у /src/api/

Специфічні стандарти API

Валідація запитів

• Використовувати Zod для валідації схем
• Завжди валідувати вхідні дані
• Повертати 400 з помилками валідації
• Включати деталі помилок на рівні полів

Автентифікація

• Усі ендпоінти вимагають JWT-токен
• Токен у заголовку Authorization
• Токен закінчується через 24 години
• Реалізувати механізм refresh-токенів

Формат відповіді

Усі відповіді мають дотримуватися цієї структури:

{
  "success": true,
  "data": { /* фактичні дані */ },
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

Відповіді з помилками:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Повідомлення для користувача",
    "details": { /* помилки полів */ }
  },
  "timestamp": "2025-11-06T10:30:00Z"
}

Пагінація

• Використовувати пагінацію на основі курсора (не зсуву/offset)
• Включати булеве поле hasMore
• Максимальний розмір сторінки: 100
• Розмір сторінки за замовчуванням: 20

Обмеження частоти запитів (Rate Limiting)

• 1000 запитів на годину для автентифікованих користувачів
• 100 запитів на годину для публічних ендпоінтів
• Повертати 429 при перевищенні
• Включати заголовок retry-after

Кешування

• Використовувати Redis для кешування сесій
• Тривалість кешу: 5 хвилин за замовчуванням
• Інвалідувати при операціях запису
• Тегувати ключі кешу типом ресурсу

---

Останнє оновлення: 9 квітня 2026