REST API Style Guide: Batch, async, локализация

17. Batch-операции

Batch-операции обрабатываются поэлементно (partial success): ошибка одного элемента не отменяет обработку остальных. Если требуется атомарность (all-or-nothing), это явно указывается в документации эндпоинта и реализуется через транзакцию на стороне сервера.

17.1 Обязательно

R-BATCH-1. Эндпоинт оформляется как POST /resources/batch (или POST /resources/batch/<action> для batch-команд):
```
POST /api/v1/orders/batch
POST /api/v1/notifications/batch/send
```

R-BATCH-2. Формат запроса — { "items": [...] }:

{
  "items": [
    { "productId": "aaa", "quantity": 2 },
    { "productId": "bbb", "quantity": 1 },
    { "productId": "ccc", "quantity": 5 }
  ]
}

R-BATCH-3. Код ответа — 200 OK (даже если часть элементов не прошла). Тело содержит результат по каждому элементу и агрегированный summary:
```
{
  "results": [
    { "index": 0, "status": "SUCCESS", "orderId": "..." },
    { "index": 1, "status": "ERROR", "error": { "code": "INSUFFICIENT_STOCK", "detail": "Товар bbb отсутствует на складе" } },
    { "index": 2, "status": "SUCCESS", "orderId": "..." }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}
```
- index — позиция элемента в исходном массиве (0-based).
- status — SUCCESS или ERROR.
- При ERROR — упрощённый объект error с code и detail (не полный ProblemDetails, т. к. ошибка относится к элементу batch, а не к HTTP-запросу).
- summary — агрегация: total, succeeded, failed.
R-BATCH-4. Максимальный размер batch указывается в документации (например, 100 элементов).
R-BATCH-5. При превышении размера — 400 Bad Request с code: BATCH_SIZE_EXCEEDED.

18. Длительные операции (async)

Для операций, которые не могут завершиться за время HTTP-запроса.

18.1 Обязательно

R-ASYNC-1. Паттерн polling:

Клиент отправляет запрос.
Сервер возвращает 202 Accepted с заголовком Location на задачу и телом, содержащим taskId, status, statusUrl.
Клиент периодически опрашивает задачу до завершения.

POST /api/v1/reports/generate
Content-Type: application/json

{ "dateFrom": "2025-01-01", "dateTo": "2025-12-31" }

Ответ:

HTTP/1.1 202 Accepted
Location: /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "createdAt": "2025-03-15T10:30:00Z",
  "statusUrl": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000"
}

R-ASYNC-2. Опрос статуса — GET /api/v1/tasks/{id}.

Пока задача выполняется:

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING",
  "progress": 45,
  "createdAt": "2025-03-15T10:30:00Z"
}

После завершения:

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "progress": 100,
  "createdAt": "2025-03-15T10:30:00Z",
  "completedAt": "2025-03-15T10:35:00Z",
  "resultUrl": "/api/v1/reports/550e8400-e29b-41d4-a716-446655440000"
}

При ошибке:

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "FAILED",
  "createdAt": "2025-03-15T10:30:00Z",
  "completedAt": "2025-03-15T10:32:00Z",
  "error": {
    "code": "REPORT_GENERATION_FAILED",
    "detail": "Не удалось сформировать отчет: данные за период отсутствуют"
  }
}

R-ASYNC-3. Допустимые статусы задачи:
- PENDING — задача создана, ожидает обработки
- PROCESSING — выполняется
- COMPLETED — завершена, результат доступен по resultUrl
- FAILED — завершена с ошибкой, подробности в error
R-ASYNC-4. При COMPLETED — поле resultUrl обязательно. При FAILED — поле error обязательно.

19. Локализация

19.1 Обязательно

R-LOC-1. Клиент указывает предпочитаемый язык через заголовок Accept-Language:
```
GET /api/v1/orders/{id}
Accept-Language: ru
```
R-LOC-2. Если Accept-Language не указан — сервер использует язык по умолчанию, определённый для проекта (например, ru).
R-LOC-3. Локализуются:
- detail в ProblemDetails
- message в violations

19.2 Запрещено

R-LOC-X1. Локализация enum-кодов и URI:
- code — всегда на английском (ORDER_EMPTY, не ЗАКАЗ_ПУСТОЙ)
- title — стандартное название HTTP-статуса на английском (Bad Request, Not Found)
- type — URI/URN, всегда на английском
- Имена полей в JSON — orderId, не идЗаказа