From f3c3e33289003f6f07d41af00d79df277f33032b Mon Sep 17 00:00:00 2001 From: "Zimin A.N." Date: Wed, 20 May 2026 11:52:04 +0300 Subject: [PATCH] =?UTF-8?q?docs(cheatsheet):=20=D0=B4=D0=BE=D0=B1=D0=B0?= =?UTF-8?q?=D0=B2=D0=B8=D1=82=D1=8C=20=D0=BA=D0=BE=D0=BD=D0=BA=D1=80=D0=B5?= =?UTF-8?q?=D1=82=D0=BD=D1=8B=D0=B5=20=D0=BF=D1=80=D0=B8=D0=BC=D0=B5=D1=80?= =?UTF-8?q?=D1=8B=20=D1=81=20=D1=80=D0=B5=D0=B0=D0=BB=D1=8C=D0=BD=D1=8B?= =?UTF-8?q?=D0=BC=D0=B8=20dicts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit После Postman demo audit — в cheatsheet не хватало живых примеров, которые можно скопировать и сразу проверить. Добавил: * FK-зависимость: GET /dictionaries/satellite_type/dependents → [{sourceDict: spacecraft, sourceField: satellite_type_code, onClose: BLOCK, activeRecordsInSourceDict: 14}] + список других живых FK на staging (ground_station, country etc). * Локализация записи через Accept-Language: ru: НАСА / Глобальный мониторинг суши и атмосферы en: NASA / Global land and atmosphere monitoring + warning что ?locale= игнорируется и schema endpoint вообще не локализуется. * Time-travel: 14.05.2026 12:00 → 200, 14.05.2026 00:00 → 404 record_not_active (ожидаемое поведение, не bug). * History и changelog/diff живые примеры с test1. Также убрал password-grant из Auth (используется client_credentials — это правильный flow для server-to-server интеграторов). И добавил dependents проверку в 60-second smoke. --- docs/integration/api-cheatsheet.md | 77 ++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/integration/api-cheatsheet.md b/docs/integration/api-cheatsheet.md index c019b10..64f5481 100644 --- a/docs/integration/api-cheatsheet.md +++ b/docs/integration/api-cheatsheet.md @@ -9,11 +9,12 @@ ## Auth ```bash +# client_credentials (для service-to-service интеграторов) TOKEN=$(curl -s -X POST https://auth.nstart.space/realms/nstart/protocol/openid-connect/token \ - -d client_id=ordinis -d grant_type=password -d scope=openid \ - -d username=$USER -d password=$PASS | jq -r .access_token) + -d grant_type=client_credentials \ + -d client_id=$KC_CLIENT_ID -d client_secret=$KC_CLIENT_SECRET | jq -r .access_token) -curl -H "Authorization: Bearer $TOKEN" $ORDINIS/api/v1/me/notifications/settings +curl -H "Authorization: Bearer $TOKEN" $ORDINIS/api/v1/spacecraft/records?as_scope=PUBLIC,INTERNAL ``` Scopes: `PUBLIC` (anon ok) · `INTERNAL` (auth) · `RESTRICTED` (admin). @@ -185,6 +186,75 @@ Action types (13): `DICTIONARY_CREATED · SCHEMA_UPDATED · SCHEMA_PUBLISHED · | 502 | `llm_error` | AI: LLM upstream | | 503 | `circuit_open` | AI: circuit breaker | +## Реальные примеры (staging 265) + +### FK-зависимость: кто использует справочник + +```bash +curl -s "$ORDINIS/api/v1/dictionaries/satellite_type/dependents" | jq +# [ +# { +# "sourceDict": "spacecraft", +# "sourceDisplayName": "Космические аппараты", +# "sourceField": "satellite_type_code", +# "targetField": "code", +# "onClose": "BLOCK", +# "activeRecordsInSourceDict": 14 +# } +# ] +``` + +**Семантика**: `spacecraft.satellite_type_code` ссылается на `satellite_type.code`. На staging 14 КА используют этот справочник, и `onClose: BLOCK` означает что нельзя удалить тип КА пока на него ссылаются записи (без cascade-close). + +Другие живые FK на staging: +- `ground_station` ← `antenna.ground_station` (4 records, BLOCK) +- `spacecraft_status` ← `spacecraft.status` +- `country` ← `spacecraft.country` + +### Локализация записи (Accept-Language) + +```bash +# default ru-RU +curl -s "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC" | jq '.data | {mission, operator}' +# {"mission": "Глобальный мониторинг суши и атмосферы", "operator": "НАСА"} + +# en-US +curl -sH "Accept-Language: en-US" \ + "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC" | jq '.data | {mission, operator}' +# {"mission": "Global land and atmosphere monitoring", "operator": "NASA"} +``` + +⚠️ Только Accept-Language header. `?locale=` query param backend сейчас игнорирует. Schema endpoint (`/dictionaries/{name}`) **не локализуется** вообще — всегда возвращает на defaultLocale. + +### Time-travel: запись на момент в прошлом + +```bash +# Запись на 14.05.2026 12:00 UTC (точно после её validFrom = 11:34) +curl -s "$ORDINIS/api/v1/test1/records/Dima_record_test_1?as_scope=PUBLIC&at=2026-05-14T12:00:00Z" \ + | jq '{businessKey, validFrom, validTo, data}' +# 200 OK — запись действительная на указанный момент + +# До validFrom → 404 record_not_active (это ожидаемо) +curl -s "$ORDINIS/api/v1/test1/records/Dima_record_test_1?as_scope=PUBLIC&at=2026-05-01T00:00:00Z" | jq '.code' +# "record_not_active" +``` + +### History — все ревизии записи + +```bash +curl -s "$ORDINIS/api/v1/dictionaries/spacecraft/records/1999-068A/history?as_scope=PUBLIC" | jq '.[0] | {revisionNumber, revisionType, updatedAt}' +``` + +### Schema time-travel (changelog diff) + +```bash +# Список ревизий +curl -s "$ORDINIS/api/v1/dictionaries/test1/changelog" | jq '.currentVersion, (.entries | length)' + +# Diff конкретной ревизии (before/after JSON-Schema) +curl -s "$ORDINIS/api/v1/dictionaries/test1/changelog/22/diff" | jq '{eventType, occurredAt, before: .before.properties | keys, after: .after.properties | keys}' +``` + ## 60-second smoke ```bash @@ -195,6 +265,7 @@ curl -s $ORDINIS/api/v1/version | jq # curl -s $ORDINIS/api/v1/dictionaries | jq 'length' # 37 на prod / 39 на staging curl -s $ORDINIS/api/v1/dictionaries/spacecraft | jq '.scope' # "PUBLIC" curl -s "$ORDINIS/api/v1/spacecraft/records?as_scope=PUBLIC" | jq '.[0].businessKey' +curl -s "$ORDINIS/api/v1/dictionaries/satellite_type/dependents" | jq 'length' # 1 (spacecraft зависит) curl -s "$ORDINIS/api/v1/search?q=spacecraft" | jq '.total' # >0 curl -s $ORDINIS/api/v1/ai/info | jq '.enabled' # true / false ```