mdm-ordinis/docs/integration/api/best-practices.md

Best practices

Чек-лист для consumer'ов Ordinis API.

Идентификация записей

1. Используй businessKey, не UUID. UUID — внутренний идентификатор записи и меняется при создании новой версии (через update). businessKey стабилен через всю жизнь записи.

2. Не делай FK на копию справочника. Если копируешь данные к себе для snapshot — храни business_key VARCHAR как key, не id UUID либо internal_id. Это устойчиво к updates.

Авторизация

3. Кэшируй access token с TTL = expires_in - 30s. Не делай новый token request на каждый API call — Keycloak rate limits + латентность.

4. Refresh JWT перед TTL. Не дожидайся 401 — большинство Keycloak SDK рефрешат автоматически.

5. Не храни client_secret в коде / git. Vault либо secret manager.

Чтение

6. Кэшируй per (dictionary, lang). Inline в коде — staleTime / TTL. См. Caching.

7. Используй ?lang= параметр для flatten i18n полей если UI на одном языке. Без lang ответ возвращает {ru-RU: "...", en-US: "..."} объект — лишний размер payload + проще баг.

8. Не запрашивай history endpoint на hot path. История нужна только admin UI / audit. Список + by-key endpoints достаточны для типичного consumer.

Запись (admin only)

9. Не пиши массовых update'ов через одиночные API calls. Ordinis оптимизирован под редкие записи и частые чтения. Для bulk import используй POST /admin/bundle/import (через bundle Maven module).

10. Bulk close через _bulk-close endpoint, не loop одиночных POST. Per-record transactions, classification (skipped vs error vs closed), меньше latency.

11. Bulk export CSV через _export?format=csv для extracting filtered данные в legacy системы.

Обработка событий

12. Idempotency — события at-least-once, могут прийти дважды. Используй (dictionary, businessKey, txTime, version) либо deliveryId (для webhooks) как dedup key.

13. Async обработка — отвечай webhook'у 202 Accepted сразу, обрабатывай в background. Жёсткий timeout 10s.

14. HMAC verify первым — до парсинга JSON. Защита от spoofed events.

15. Stale cache на 5xx / timeout — отдавай старые данные с warn'ом, не падай каскадно.

Производительность

16. Parallel-fetch related dictionaries при cascading select:

    const [spacecrafts, satTypes, instruments] = await Promise.all([
      fetch('/api/v1/spacecraft/records?lang=ru'),
      fetch('/api/v1/satellite_type/records?lang=ru'),
      fetch('/api/v1/instrument/records?lang=ru'),
    ])
    

    Не последовательные await, не N+1 loops.

17. Cascading filters в memory — после loading dictionaries фильтруй клиент-side вместо новых API calls:

    const allowedFormats = formats.filter(f =>
      instrument.data.supportedFormatCodes.includes(f.businessKey))
    

18. Не делай polling в tight loop — используй webhooks либо Kafka events для realtime invalidation. Polling каждые 5 мин — OK, каждые 10 сек — нет.

Error handling

19. Don't retry 4xx (кроме 401 и 429). Permanent errors требуют code fix, не retry.

20. Exponential backoff на 5xx / timeout. Base 0.5s, multiplier 2, jitter 0-0.5s, max 5 attempts. См. Errors.

21. Сохраняй traceId при эскалации в Ordinis team. Без traceId investigation в Tempo занимает в 10x дольше.

Bundle versioning

22. Forward compatibility — допускай новые поля в API responses которые ты не знаешь. Не fail on unknown fields. Schema validation у consumer'а должна быть additionalProperties: true (либо аналог).

23. Подписывайся на nsi.dictionary.changed events для новых справочников — они появляются с минор-bump bundle.

24. Monitor schema versions в GET /dictionaries response — если schemaVersion поменялся, проверь твой mapping не сломался.

Безопасность

25. HTTPS обязателен — webhook URLs тоже только https. SSRF guard блокирует http:// и private CIDR.

26. Не log access tokens в plaintext. Большинство logging frameworks имеют redaction patterns для Authorization header.

27. Rotate client_secret регулярно. Раз в квартал — minimum, раз в месяц — recommended для production. Coordinate с Ordinis team при rotation.

Коммуникация с командой

28. Прежде чем bulk import > 1000 records — talk to Ordinis team. У нас есть staging environment + bulk-import endpoint без rate limits.

29. Запрашивай новый scope / role через zimin.an@nstart.space либо issue с label keycloak-role-request.

30. При проблеме: воспроизведи на staging, скопируй traceId, открой issue. Скриншоты UI ошибок помогают.

Тестирование

31. Mock Ordinis в unit tests — не завись от availability staging cluster. Нашa OpenAPI spec accurate, генерируй mock client.

32. Integration tests против staging — не prod. Staging данные — тестовые, можно create/close без последствий.

33. Load tests на staging в low-traffic окно. Координируй с Ordinis team — мы можем включить дополнительные replicas для вашего теста.

Reference: bundle cuod

См. Bundle cuod — список 40 справочников, их связи, типичные operations.

Дальше

• События — push-обновления
• Caching — стратегии кэша
• Errors — обработка ошибок