Принципы проектирования API

Previous Next

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

Консистентность

  • Единый стиль именования: snake_case в proto и JSON; понятные имена методов и полей.
  • Структура ответов и ошибок единообразна в рамках платформы; см. Рекомендации по API.

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

  • gRPC: версия в пути пакета (v1); при несовместимых изменениях — новый пакет (v2) или отдельный сервис. Обратная совместимость: не удалять поля, не менять типы; новые поля — optional.
  • REST: версия в URL (/api/v1/...); при breaking changes — новая мажорная версия. Депрекации объявляются заранее с сроком поддержки.

Ошибки

  • Использовать стандартные коды (gRPC: INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS и т.д.; HTTP: 400, 404, 409, 500). В теле ошибки — структурированное описание для клиента без утечки внутренних деталей.
  • Доменные ошибки маппятся на коды однозначно; логирование полного контекста на стороне сервера.

Идемпотентность и безопасность

  • Мутирующие операции при необходимости поддерживают idempotency key для безопасного retry.
  • Аутентификация на границе (API Gateway); не передавать секреты и PII в логах и в ответах.

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

Границы доменов Принципы проектирования событий