Проектирование API

Новый раздел

Этот раздел добавлен как дополнение к исходной структуре — стандарты проектирования API критичны для команды.

Принципы

1. Единообразие — единообразные эндпоинты, именование, формат ошибок
2. Обратная совместимость — не ломаем существующих клиентов
3. Сначала контракт — API-контракт определяется до реализации
4. Документация как код — OpenAPI/Protobuf как источник истины

REST API

URL-конвенции

GET    /api/v1/users          — список
GET    /api/v1/users/{id}     — одна сущность
POST   /api/v1/users          — создание
PUT    /api/v1/users/{id}     — полное обновление
PATCH  /api/v1/users/{id}     — частичное обновление
DELETE /api/v1/users/{id}     — удаление

• Существительные во множественном числе: /users, не /user
• Kebab-case для составных URL: /payment-methods
• Вложенность не глубже 2 уровней: /users/{id}/orders

Формат ответов

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

Формат ошибок

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Not enough balance to complete the transaction",
    "details": [
      {
        "field": "amount",
        "reason": "Requested 100.00, available 50.00"
      }
    ]
  }
}

HTTP Status Codes

Код	Когда
200	Успешный запрос
201	Ресурс создан
204	Успешно, нет тела ответа
400	Невалидный запрос
401	Не аутентифицирован
403	Нет прав
404	Ресурс не найден
409	Конфликт (duplicate, race condition)
422	Валидация не прошла
429	Rate limit
500	Внутренняя ошибка

gRPC

• Protobuf как IDL
• Следуем Google API Design Guide
• Версионирование через package name: ventra.payments.v1

Версионирование API

• Мажорная версия в URL: /api/v1/, /api/v2/
• Минорные изменения — backward compatible, без смены версии
• Deprecated эндпоинты: заголовок Sunset + документация миграции

Пагинация

Используем cursor-based pagination для больших коллекций:

GET /api/v1/orders?cursor=abc123&limit=20

Offset-based допустим для админ-панелей и небольших наборов данных.