mdm-ordinis/docs/integration/api/index.md

Интеграция по API — обзор

Этот раздел описывает как backend-сервисы (Альтум, геопортал, BI и т.д.) читают и пишут справочники Ordinis НСИ ЦУОД.

Owner: Ordinis team — zimin.an@nstart.space.

С чего начать

1. Получи Keycloak service account — нужен для всех API вызовов.
2. Прочитай read-side endpoints — как получить данные.
3. Выбери стратегию обновления — TTL, webhooks, либо Kafka events.

Что Ordinis даёт

• Bitemporal CRUD для справочников — validFrom / validTo + revision history через Hibernate Envers.
• Multi-locale — каждое поле может иметь {ru-RU, en-US, ...} варианты. Flatten через ?lang= параметр.
• Cross-dictionary FK через x-references schema extension. Server-side валидация на CRUD + orphan scanner periodic.
• Geometry support — PostGIS для bbox/polygon фильтров (spacecraft.aoi, mission.coverage_area).
• Audit log — все изменения через /api/v1/admin/audit (UI: /audit).
• Outbox + Kafka — at-least-once delivery всех изменений в 3 топика.
• Webhooks — push-уведомления HTTP к зарегистрированным URLs (для consumers без Kafka access).
• Bulk operations — multi-select close + CSV export.
• Schema workflow — maker-checker approval для изменения schemas (drafts + review + publish). См. Schema workflow API.
• Full changelog timeline — /dictionaries/{name}/changelog объединяет definition CRUD + draft workflow events с kind field для UI rendering.

Что Ordinis НЕ делает

• Не хранит "снимок на момент заказа" — для этого consumer должен сделать snapshot rough copy в свою БД (см. Caching → Snapshot strategy).
• Не enforce'ит FK на уровне DB — это NoSQL-style references поверх JSONB. Cascade rules в roadmap (см. design dict-relationships-v2).
• Не обеспечивает realtime sync — TTL = 5 мин минимум либо event-driven invalidation.

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

• API — /api/v1/... стабилен. Breaking changes только через major (v2).
• Bundle (cuod-bundle) — semver. Minor bump при schema изменении, major при удалении справочника. См. Bundle cuod.

Глоссарий

Термин	Значение
Dictionary	Справочник (например spacecraft, satellite_type).
Record	Запись в справочнике с уникальным businessKey.
businessKey	Стабильный идентификатор (string). Не меняется при update.
Bundle	Maven module с schemas + seed data. ЦУОД bundle = 40 справочников.
Scope	Уровень доступа: PUBLIC / INTERNAL / RESTRICTED.
Bitemporal	Запись имеет validFrom/validTo + revision history (transaction time).
x-references	JSON Schema extension для cross-dictionary FK.