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 ```