docs(api): Quick Start guide + Cheat Sheet для интеграторов

2026-05-17 13:14:33 +00:00
parent 2f06b408b8
commit 04e8251941
2 changed files with 760 additions and 0 deletions
@@ -0,0 +1,188 @@
+# 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
+
+```bash
+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
+
+```bash
+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 — единая форма
+
+```json
+{ "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
+
+```bash
+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`