Рекомендации по API

Previous Next

Рекомендации по проектированию и реализации API (gRPC и REST) в AIOps.

gRPC (internal APIs)

Контракты (Proto)

  • Файлы в proto/aiops/<domain>/v1/.
  • Используется версионирование в пути (v1); обратная совместимость при изменениях.
  • Именование: CreateUserRequest, CreateUserResponse, сервис IdentityService.

Коды ошибок

  • OK — успех.
  • INVALID_ARGUMENT — некорректные входные данные.
  • NOT_FOUND — сущность не найдена.
  • ALREADY_EXISTS — конфликт (например, username уже занят).
  • PERMISSION_DENIED — нет прав.
  • UNAUTHENTICATED — не авторизован.
  • INTERNAL — внутренняя ошибка (без утечки деталей наружу).

Доменные ошибки маппятся на эти коды; в details можно передавать структурированную информацию для клиента.

Идемпотентность

  • Методы создания/обновления при необходимости поддерживают идемпотентность по idempotency_key в запросе.
  • Для событий в Kafka ключ сообщения (например, aggregate id) позволяет потребителям дедуплицировать.

Метаданные и контекст

  • Request context (user_id, request_id, trace_id) передается через gRPC metadata и пробрасывается в логи и трейсы.

REST (public APIs)

  • Публичные API (Session Token service, Account service, Auth Service) следуют REST-принципам.
  • Версионирование в URL: /api/v1/....
  • Стандартные коды HTTP: 200, 201, 400, 401, 403, 404, 409, 500.
  • Тело ошибок — JSON с кодом, сообщением и опционально details.

Безопасность

  • Все публичные API за API Gateway; аутентификация через JWT.
  • Internal gRPC не экспонируется наружу; в кластере — сетевые политики и mTLS при необходимости.
  • Не логировать и не возвращать в ответах чувствительные данные (пароли, токены, PII в plaintext).

Связанные страницы

Паттерны сервисов Событийные паттерны