Перейти к содержанию

Описание API

Код РД (ГОСТ 34.201-89): ПА «Описание программного обеспечения»

Документ описывает программное обеспечение BOX5-DIT-MGSN в части API, межсервисных интерфейсов, структуры программных компонентов и порядка поставки. Документ подготовлен как типовое описание API для эксплуатационных контуров проекта «BOX5-DIT-MGSN». DEV, TEST и PROD используют единый состав API-контрактов применяемых доменов; различия между контурами относятся к топологии, количеству узлов, набору подключённых источников данных и значениям эксплуатационной конфигурации.

В ПА фиксируются:

  • состав частей программного обеспечения и их API-границы;
  • реестр интерфейсов между ui-rest, statistics, inference, extended-inference, severstal, data-storage, kafka-domain, elk-log и node-red-sandbox;
  • REST, GraphQL, WebSocket, gRPC, Kafka, S3, SQL и файловые способы обмена;
  • общие требования к API: авторизация, форматы данных, ошибки, логирование, обратная совместимость и правила изменения контрактов;
  • базовые правила асинхронного обмена и обработки дублей;
  • CI/CD, артефакты поставки, развёртывание и rollback;
  • приложение с OpenAPI / Swagger-спецификациями применяемых API-групп.

Чувствительная информация, включая JWT, пароли, ключи доступа, постоянные токены, внутренние DSN, реальные адреса внешних систем и контурные учётные данные, в документ не включается. Для REST endpoint-ов детальные схемы запросов и ответов приведены в приложении OpenAPI; для внутренних Kafka/gRPC/S3/SQL-интерфейсов фиксируется граница обмена, владелец данных и применяемый протокол.

flowchart LR client["Пользователь / API-клиент"] gateway["ui-nginx + ui-rest-to-gprc
единая API-граница"] stats["statistics
auth, камеры, события, отчёты"] inf["inference + extended-inference
медиа, NRI, ресурсы"] svr["severstal
интеграции заказчика"] ds["data-storage
MinIO / DTS"] kafka["kafka-domain
асинхронный обмен"] obs["elk-log
логи и метрики"] client -->|"HTTP / REST / GraphQL / WebSocket"| gateway gateway --> stats gateway --> inf gateway --> svr gateway --> ds stats <--> kafka inf <--> kafka svr <--> kafka stats -.-> obs inf -.-> obs svr -.-> obs

Исходный Mermaid-код схемы: ПА-MER-020. Описание API.

Состав документа