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

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

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

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

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

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

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

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

Відповіді з помилками:
```json
{
  "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