API контракты
NOTE
Статус: Target schemas. Описание целевых схем данных. Миграции и реальные таблицы в
backend/migrations/могут отставать от документа. Правила маркировки — в50-processes/documentation-standard.md.
Раздел собирает все внешние HTTP-контракты Tracium. Формат — OpenAPI 3.1
с дополнительным AsyncAPI (WebSocket) и gRPC (.proto) описаниями рядом.
Интерактивный просмотр (Swagger UI)
api-server монтирует эти же спеки и отдаёт их вместе с Swagger UI. Ничего
дополнительно собирать не нужно — после make web-up:
| URL | Что это |
|---|---|
https://docs.tracium.dev/api-contract/ | Swagger UI под docs-доменом (основной вход) |
https://docs.tracium.dev/openapi/public.yaml | Public API спека (docs-домен) |
https://docs.tracium.dev/openapi/admin.yaml | Admin API спека (docs-домен) |
https://api.tracium.dev/docs/ | Тот же UI на api-домене (raw) |
Контракт живёт на docs-поддомене через nginx-локацию /api-contract/ и
/openapi/, которые проксируются в api-server. Спеки монтируются read-only из
docs/docs/20-architecture/schemas/api/.
Единственный источник истины — эти YAML-файлы. Swagger UI загружается из CDN
(unpkg.com/swagger-ui-dist@5).
Если каталог спек не найден (нет монтирования, env API_OPENAPI_DIR не
задан), /docs/ всё равно отвечает HTML, а /openapi/*.yaml возвращает
структурированный 404 с code: "openapi_unavailable".
Канонические файлы
| Файл | Покрытие |
|---|---|
public-api.openapi.yaml | REST-контур клиентского API. servers уже включают /v1, поэтому path keys пишутся как /products, /search/proposals, /whoami; внешний URL получается /v1/.... Auth для public data API — API token trk_*, см. ADR-0051. |
admin-api.openapi.yaml | Admin API как есть (AS-SHIPPED): реально реализованные core handlers и platform job-history endpoints. Строго линтуется CI-job backend-openapilint на паритет с кодом. |
cabinet-api.openapi.yaml | Cabinet API под /api/cabinet/* (JWT-cookie). Покрывает keys / scopes / profile / credentials.suppliers.catalog. Линтуется через make backend-openapilint-cabinet. |
cabinet-customer-data-api.openapi.yaml | Customer-callable endpoints за пределами /api/cabinet/* префикса. На 2026-05-06 — только /api/v1/credentials/* (customer-scope CRUD). JWT-cookie auth. Spec поддерживается вручную; lint автоматизация отложена до раздела handler.go на admin/client файлы. |
admin-api-target.openapi.yaml | Admin API целевой (TARGET, aspirational roadmap): полный замысел на все BC — customers, organizations, identity-profiles, enrichment, moderation, plans, suppliers, offers, credentials, relationships, connectors. Линтером не проверяется; служит design-reference. Перенести запись сюда при реализации endpoint → удалить из target. |
grpc/public_api.proto | gRPC-зеркало public REST (ADR-0015) |
asyncapi/public-ws.yaml | WebSocket-контракт (subscriptions + push) |
connector-api.yaml | Внутренний Go-интерфейс Connector ↔ Core (не публикуется наружу) |
Как править контракт
- Обсуждение изменения фиксируется в ADR (если затрагивает границы сервиса).
- Правка вносится в соответствующий YAML / proto в этом каталоге.
- Swagger UI подхватит изменения на следующем refresh страницы (volume mount read-only, без перезапуска контейнера).
- Контрактные тесты (
50-processes/testing-strategy.md) должны пройти перед merge — см. ADR-0023.
Public API path/auth rules
- Canonical customer URLs are
/v1/*. - In
public-api.openapi.yamldo not prefix path keys with/v1; the server URL supplies that base path. - Legacy aliases under
/api/v1/*may exist in nginx/backend for compatibility, but they are not canonical SDK contract paths. cabinet-api.openapi.yamlcovers only/api/cabinet/*; do not document/api/v1/search/proposalsthere.- User JWT-cookie is for cabinet/admin UI. API tokens
trk_*are for public system-to-system calls. Details: ADR-0051.