Александр Зимин
8.6 KiB
8.6 KiB
Ordinis API · Cheat Sheet
Одностраничный референс. Полный гайд — api-quickstart.md.
Base: https://ordinis.k8s.264.nstart.cloud/api/v1 · Version: v2.36.0 · OpenAPI: /swagger-ui/index.html
Auth
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)
curl -H "Authorization: Bearer $TOKEN" $ORDINIS/api/v1/me/notifications/settings
Scopes: PUBLIC (anon ok) · INTERNAL (auth) · RESTRICTED (admin).
Read (no auth для PUBLIC)
| Verb | Path | Что |
|---|---|---|
GET |
/version |
Версия + commit + builtAt |
GET |
/dictionaries |
Список всех справочников |
GET |
/dictionaries/{name} |
Детали + JSON Schema |
GET |
/dictionaries/templates |
6 шаблонов схем |
GET |
/dictionaries/templates/{id} |
Один шаблон со schemaJson |
GET |
/dictionaries/graph/outgoing |
FK-граф между справочниками |
GET |
/dictionaries/{name}/dependents |
Кто ссылается на этот dict |
GET |
/dictionaries/{name}/changelog |
Список изменений схемы |
GET |
/dictionaries/{name}/changelog/{id}/diff |
Diff между версиями |
GET |
/dictionaries/{name}/snapshots?asOf= |
Snapshot на дату (ISO-8601) |
GET |
/{name}/records |
Список записей (⚠️ не /dictionaries/{name}/records) |
GET |
/{name}/records/{businessKey} |
Одна запись |
GET |
/{name}/records/{businessKey}/history |
История версий записи |
GET |
/{name}/records/scheduled-summary |
Будущие версии (count + nearestValidFrom) |
GET |
/{name}/records/export.csv |
Bulk export |
GET |
/search?q=&limit= |
Smart search (≥3 chars, trigram) |
GET |
/ai/info |
{enabled: bool} AI feature flag |
Query params (records)
?limit=50&offset=0 pagination
?status=ACTIVE&country=RU фильтр по атрибутам схемы
?scope=INTERNAL если есть права
?asOf=2026-03-15T00:00:00Z bitemporal cut (где поддержано)
Write (требует auth)
| Verb | Path | Что |
|---|---|---|
POST |
/{name}/records |
Создать запись (если approval не нужен) |
PUT |
/{name}/records/{businessKey} |
Обновить |
DELETE |
/{name}/records/{businessKey} |
Soft-delete (tombstone) |
POST |
/{name}/records/bulk-close |
Массовое закрытие |
POST |
/{name}/records/{businessKey}/cascade-close |
Закрыть с зависимыми |
GET |
/{name}/records/{businessKey}/cascade-preview |
Preview каскада |
PATCH |
/dictionaries/{name}/schema |
Изменить схему inline (non-breaking) |
PUT |
/dictionaries/{name} |
Полностью пересоздать (breaking) |
Workflow (drafts + approvals)
| Verb | Path | Что |
|---|---|---|
POST |
/dictionaries/{name}/records/drafts |
Создать record draft |
POST |
/dictionaries/{name}/drafts |
Создать schema draft |
GET |
/dictionaries/{name}/drafts |
Список schema drafts по dict |
GET |
/dictionaries/{name}/drafts/active |
Активный draft (200+null если нет) |
GET |
/dictionaries/{name}/drafts/{id} |
Один draft |
DELETE |
/dictionaries/{name}/drafts/{id} |
Withdraw |
POST |
/dictionaries/{name}/drafts/{id}/review |
Назначить ревью |
POST |
/dictionaries/{name}/drafts/{id}/decision |
Approve/reject schema draft |
POST |
/dictionaries/{name}/drafts/{id}/publish |
Опубликовать после approve |
GET |
/drafts/me |
Мои record-drafts (status filter) |
GET |
/drafts/{id} |
Один record draft |
DELETE |
/drafts/{id} |
Withdraw record draft |
POST |
/drafts/{id}/approve |
Одобрить (body: {comment}) |
POST |
/drafts/{id}/reject |
Отклонить (body: {comment}) |
GET |
/admin/reviews/pending |
Очередь ревьюера (records) |
GET |
/admin/schema-reviews/pending |
Очередь ревьюера (schemas) |
GET |
/admin/schema-drafts/me |
Мои schema drafts |
AI
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
$ORDINIS/api/v1/ai/suggest-field \
-d '{"prompt":"контактный email оператора"}'
Limits: 30 req/min на IP, circuit breaker 10 fails / 60s → open 5min (503 circuit_open).
Notifications (per-user, auth)
| Verb | Path | Что |
|---|---|---|
GET |
/me/notifications |
Bell-bar feed |
POST |
/me/notifications/{id}/read |
Mark as read |
POST |
/me/notifications/read-all |
Mark all as read |
GET |
/me/notifications/preferences |
Per-event matrix |
PUT |
/me/notifications/preferences |
Сохранить матрицу |
GET |
/me/notifications/settings |
Quiet hours config |
PUT |
/me/notifications/settings |
Сохранить quiet hours |
Webhooks (admin)
| Verb | Path | Что |
|---|---|---|
GET |
/admin/webhooks/subscriptions |
Список подписок |
POST |
/admin/webhooks/subscriptions |
Создать (secret в ответе, один раз) |
GET |
/admin/webhooks/subscriptions/{id} |
Детали |
PUT |
/admin/webhooks/subscriptions/{id} |
Обновить |
DELETE |
/admin/webhooks/subscriptions/{id} |
Удалить |
POST |
/admin/webhooks/subscriptions/{id}/rotate-secret |
Перевыпуск ключа |
POST |
/admin/webhooks/subscriptions/{id}/test |
Test delivery |
GET |
/admin/webhooks/subscriptions/{id}/stats |
Histogram (24h/7d) |
GET |
/admin/webhooks/subscriptions/{id}/deliveries |
Recent deliveries |
GET |
/admin/webhooks/deliveries/dlq |
DLQ list |
POST |
/admin/webhooks/deliveries/{id}/retry |
Manual retry |
Headers delivered
X-Ordinis-Event: RecordCreated
X-Ordinis-Signature: sha256=<hex> HMAC-SHA256(body, secret)
X-Ordinis-Delivery: del_01HXY...
User-Agent: ordinis-alerts
Event types
RecordCreated · RecordUpdated · RecordClosed · RecordRestored · BulkClosed · SchemaDraftSubmitted · SchemaDraftApproved · SchemaDraftRejected · SchemaDraftPublished · RecordDraftSubmitted · RecordDraftApproved
Audit (admin)
| Verb | Path | Что |
|---|---|---|
GET |
/admin/audit?dictionary=&action=&user=&dateFrom=&dateTo= |
Фильтрованный аудит |
GET |
/admin/audit/export.csv |
Полный экспорт |
GET |
/admin/audit/export-selected.csv |
Selected ids экспорт |
Action types (13): DICTIONARY_CREATED · SCHEMA_UPDATED · SCHEMA_PUBLISHED · RECORD_CREATED · RECORD_UPDATED · RECORD_CLOSED · RECORD_RESTORED · DRAFT_CREATED · DRAFT_SUBMITTED · DRAFT_APPROVED · DRAFT_REJECTED · DRAFT_WITHDRAWN · REVIEWER_ASSIGNED
Outbox (admin)
| Verb | Path | Что |
|---|---|---|
GET |
/admin/outbox/stats |
Pending/DLQ counters |
GET |
/admin/outbox/dlq |
DLQ events list |
Errors — единая форма
{ "status": 422, "code": "validation_failed", "message": "...",
"details": {}, "traceId": "...", "timestamp": "..." }
| HTTP | code | |
|---|---|---|
| 400 | bad_request |
Невалидный body |
| 401 | unauthorized |
Нет/просрочен токен |
| 403 | forbidden |
Scope/role не пускает |
| 404 | not_found |
Нет такого ресурса |
| 409 | conflict |
Concurrent update / unique violation |
| 422 | validation_failed |
Schema validation fail |
| 429 | rate_limited |
Лимит запросов |
| 500 | internal_error |
См. traceId |
| 502 | llm_error |
AI: LLM upstream |
| 503 | circuit_open |
AI: circuit breaker |
60-second smoke
ORDINIS=https://ordinis.k8s.264.nstart.cloud
curl -s $ORDINIS/api/v1/version | jq # alive
curl -s $ORDINIS/api/v1/dictionaries | jq 'length' # >= 40
curl -s $ORDINIS/api/v1/dictionaries/spacecraft | jq '.scope' # "PUBLIC"
curl -s "$ORDINIS/api/v1/spacecraft/records?limit=1" | jq '.[0].businessKey'
curl -s "$ORDINIS/api/v1/search?q=Sentinel" | jq '.total' # 12
curl -s $ORDINIS/api/v1/ai/info | jq '.enabled' # true
Связанные доки
api-quickstart.md · bundle-format-spec.md · docs/changelog.md · Swagger UI /swagger-ui/index.html