docs: Diplodoc setup + полное руководство интеграции по API
Новая документация-as-code на платформе Diplodoc (Yandex open-source) с YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно. Что добавлено: - package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar - index.md — главная страница с tabs для разных audiences - README.md — инструкция для contributors Раздел integration/api/ — 11 страниц про интеграцию consumers: - index — обзор + глоссарий - auth — Keycloak service accounts, scope mapping - read-endpoints — GET /dictionaries, list/by-key, spatial filters - events — Kafka outbox топики, partition keys, idempotency, DLQ - webhooks — HMAC, SSRF guard, retry policy, test ping endpoint - bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export - x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview - caching — TTL / push / snapshot strategies, hybrid pattern - errors — full error code reference (validation/auth/conflict/server), retry strategy - best-practices — 33 numbered rules для consumers - bundle-cuod — все 40 справочников с FK графом и сценариями Обновлены: - ops/README.md — link на новую integration/api/, убран inline <br> - ops/slo.md — broken cross-repo links заменены на text references Build: cd docs && pnpm install && pnpm build → ./_dist (20 HTML files, 7.1M) pnpm serve # → http://localhost:8088 CI deploy job для GitLab Pages — в roadmap (см. docs/README.md). Существующий tech/api-integration.md оставлен в toc как legacy (содержимое мигрировано + расширено в integration/api/).
This commit is contained in:
Zimin A.N.
@@ -0,0 +1,191 @@
|
||||
# Read-side endpoints
|
||||
|
||||
Read-API в Ordinis — отдельный deployable (`ordinis-read-api`, scaled 2× в проде)
|
||||
работающий на Postgres replica. Запросы из read-api **не блокируют** writer'а.
|
||||
|
||||
Base URL:
|
||||
|
||||
| Среда | URL |
|
||||
|---|---|
|
||||
| prod | `https://ordinis.k8s.264.nstart.cloud/api/v1` |
|
||||
| staging | `https://ordinis.k8s.265.nstart.cloud/api/v1` |
|
||||
|
||||
Все endpoints требуют JWT (см. [Авторизация](auth.md)).
|
||||
|
||||
## OpenAPI / Swagger UI
|
||||
|
||||
- **Swagger UI:** `https://ordinis.k8s.264.nstart.cloud/swagger-ui.html`
|
||||
- **Spec JSON:** `https://ordinis.k8s.264.nstart.cloud/v3/api-docs`
|
||||
- **Spec YAML:** `https://ordinis.k8s.264.nstart.cloud/v3/api-docs.yaml`
|
||||
|
||||
Из spec'а можно generate'ить клиент:
|
||||
|
||||
```bash
|
||||
openapi-generator-cli generate \
|
||||
-i https://ordinis.k8s.264.nstart.cloud/v3/api-docs \
|
||||
-g python \
|
||||
-o ./altum-backend/clients/ordinis
|
||||
```
|
||||
|
||||
Поддерживаются: Python, TypeScript, Go, Java, Kotlin, Ruby и др.
|
||||
|
||||
## `GET /api/v1/dictionaries`
|
||||
|
||||
Список доступных справочников (фильтрован по scope JWT'а).
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
https://ordinis.k8s.264.nstart.cloud/api/v1/dictionaries
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "spacecraft",
|
||||
"displayName": "Космические аппараты",
|
||||
"scope": "PUBLIC",
|
||||
"schemaVersion": "1.0.0",
|
||||
"recordsCount": 4
|
||||
},
|
||||
{
|
||||
"name": "mission",
|
||||
"displayName": "Миссии / программы",
|
||||
"scope": "PUBLIC",
|
||||
"schemaVersion": "1.0.0",
|
||||
"recordsCount": 9
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## `GET /api/v1/{name}/records`
|
||||
|
||||
{% note warning %}
|
||||
|
||||
**БЕЗ префикса `/dictionaries/`!** Read-api сидит на `/api/v1/{name}/records`.
|
||||
Префикс `/api/v1/dictionaries/...` — это admin write controller (CRUD), у него
|
||||
нет bulk-list эндпоинта.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
Активные записи на момент `at` (default: сейчас).
|
||||
|
||||
### Параметры
|
||||
|
||||
| Параметр | Тип | Пример | Назначение |
|
||||
|---|---|---|---|
|
||||
| `lang` | string | `ru-RU`, `en-US` | Flatten i18n полей в строку. Короткие `ru`/`en` тоже. |
|
||||
| `at` | ISO 8601 | `2026-05-04T12:00:00+03:00` | Bitemporal query — активные на момент. |
|
||||
| `as_scope` | string | `PUBLIC,INTERNAL` | Legacy для anonymous + `allowQueryScope=true`. |
|
||||
|
||||
### Пример
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://ordinis.k8s.264.nstart.cloud/api/v1/spacecraft/records?lang=ru-RU"
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"businessKey": "RESURS-P-3",
|
||||
"displayKey": "Ресурс-П № 3",
|
||||
"scope": "PUBLIC",
|
||||
"validFrom": "2025-01-01T00:00:00+03:00",
|
||||
"validTo": "9999-12-31T23:59:59+03:00",
|
||||
"data": {
|
||||
"name": "Ресурс-П № 3",
|
||||
"satelliteTypeCode": "EARTH-OBSERVATION-OPTICAL",
|
||||
"launchDate": "2024-12-25",
|
||||
"status": "active"
|
||||
},
|
||||
"version": 2
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Без `?lang` (raw i18n)
|
||||
|
||||
```json
|
||||
"name": { "ru-RU": "Ресурс-П № 3", "en-US": "Resurs-P No.3" }
|
||||
```
|
||||
|
||||
С `?lang=ru-RU`:
|
||||
|
||||
```json
|
||||
"name": "Ресурс-П № 3"
|
||||
```
|
||||
|
||||
Если запрошенного языка нет — fallback к `default_locale` (обычно `ru-RU`).
|
||||
|
||||
## `GET /api/v1/{name}/records/{businessKey}`
|
||||
|
||||
Одна запись. Параметры те же что у list.
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://ordinis.k8s.264.nstart.cloud/api/v1/spacecraft/records/RESURS-P-3?lang=ru"
|
||||
```
|
||||
|
||||
`404 Not Found` — запись либо не существует, либо закрыта на момент `at`,
|
||||
либо вне scope JWT'а (Ordinis скрывает существование).
|
||||
|
||||
## `GET /api/v1/{name}/records/{businessKey}/history`
|
||||
|
||||
Все версии записи (включая закрытые) для построения истории изменений в UI.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"version": 1,
|
||||
"validFrom": "2024-06-01T00:00:00+03:00",
|
||||
"validTo": "2025-01-01T00:00:00+03:00",
|
||||
"data": {...},
|
||||
"txTime": "2024-06-01T10:23:45+03:00",
|
||||
"changedBy": "admin@nstart.space",
|
||||
"changeReason": "initial"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"validFrom": "2025-01-01T00:00:00+03:00",
|
||||
"validTo": "9999-12-31T23:59:59+03:00",
|
||||
"data": {...},
|
||||
"txTime": "2024-12-30T14:11:22+03:00",
|
||||
"changedBy": "admin@nstart.space",
|
||||
"changeReason": "Обновление статуса после успешного запуска"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Для consumers history endpoint обычно не нужен — это UI-feature.
|
||||
|
||||
## Spatial filters (geometry)
|
||||
|
||||
Если справочник имеет geometry поля (`spacecraft.aoi`, `mission.coverage_area`),
|
||||
поддерживаются bbox + polygon фильтры:
|
||||
|
||||
### `?bbox=` (bounding box)
|
||||
|
||||
```
|
||||
GET /api/v1/spacecraft/records?bbox=37.0,55.0,38.0,56.0
|
||||
```
|
||||
|
||||
Format: `min_lon,min_lat,max_lon,max_lat` (WGS84). Возвращает записи где
|
||||
`geometry` пересекает bbox через PostGIS `ST_Intersects` + GiST index.
|
||||
|
||||
### `?polygon=` (GeoJSON)
|
||||
|
||||
```
|
||||
GET /api/v1/spacecraft/records?polygon={"type":"Polygon","coordinates":[[[37,55],[38,55],[38,56],[37,56],[37,55]]]}
|
||||
```
|
||||
|
||||
Polygon — GeoJSON object (URL-encoded). Сложнее bbox, точнее.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [События (Kafka outbox)](events.md) — push-обновления вместо polling
|
||||
- [Bitemporal](bitemporal.md) — детали `validFrom`/`validTo` модели
|
||||
- [Caching](caching.md) — стратегии актуализации
|
||||
Reference in New Issue
Block a user