Tracium

время чтения ~2 мин.

AGENTS.md — api/

Назначение этого уровня

Контракты HTTP API, gRPC и WebSocket. OpenAPI, .proto, AsyncAPI спецификации.

Содержимое

api/
├── AGENTS.md                       # ← вы здесь
├── public-api.openapi.yaml         # REST: клиентский API (источник стартового стаба; CI генерирует из кода)
├── admin-api.openapi.yaml          # REST: админский API — AS-SHIPPED, линтуется `backend/cmd/openapilint`
├── admin-api-target.openapi.yaml   # REST: админский API — TARGET (aspirational roadmap), не линтуется
├── connector-api.yaml              # внутренний контракт ядро ↔ коннекторы (соответствует Go interface)
├── grpc/
│   ├── public_api.proto            # public-api gRPC services
│   └── README.md
└── asyncapi/
    └── public-ws.yaml              # WebSocket subscriptions

admin-api.openapi.yaml — источник истины о реально реализованных admin-endpoints. CI-job backend-openapilint строго сверяет его с mux.HandleFunc регистрациями в core HTTP handlers и platform job-history registrar — любой дрейф роняет пайплайн. Новый endpoint попадает сюда только после того, как появился handler в коде.

admin-api-target.openapi.yaml — целевой контракт, накопленный проектный roadmap (customers, organizations, identity-profiles, enrichment, moderation, plans, suppliers, offers, credentials, relationships, connectors и т.п.). Линтером не проверяется; служит design-reference для будущих BC. При реализации нового endpoint перенесите описание из target в as-shipped и уберите из target.

public-api.openapi.yaml использует servers: .../v1, поэтому path keys внутри файла пишутся без /v1: /products, /search/proposals, /whoami. Внешний URL всё равно /v1/products, /v1/search/proposals, /v1/whoami. Не добавляйте отдельные /v1/... path keys — это создаёт двойной /v1/v1/... в Swagger UI. Auth public API — API token trk_*; JWT-cookie остаётся для cabinet/admin UI. См. ADR-0051.

Остальные OpenAPI/proto/AsyncAPI файлы — стартовые заглушки. После Phase 1 источник истины переходит в код, эти файлы автогенерируются CI-задачей make api-gen. До этого момента — ручная синхронизация при PR на endpoint.

Правила

  • Все публичные контракты — в спецификациях, источник истины здесь.
  • Изменения — PR с генерацией SDK / клиентов в CI (если применимо).
  • Версионирование: /v1/..., package public.v1 для proto, breaking → /v2.
  • Для public OpenAPI version base path живёт в servers.url, не в каждом path key.
  • Для gRPC: соблюдать совместимость (не менять номера полей, не удалять, не переиспользовать).

Когда смотреть сюда

  • Добавляете endpoint / RPC / WS subscription.
  • Интегрируетесь с нашим API (генерируете client).

Связано

Вид графа

Обратные ссылки