Эндпоинты внешних сервисов, с которыми взаимодействует documentations-api
Документ описывает HTTP-эндпоинты внешних сервисов, к которым обращается сервис документаций (оба бинарника — cmd/api и cmd/filestreamer). В отличие от фронтенда, единого декларативного реестра эндпоинтов здесь нет — каждый внешний сервис инкапсулирован в собственном клиенте в каталогах clients/ и pkg/.
Как устроено взаимодействие
Клиенты создаются при старте (cmd/api/routes_api.go, cmd/filestreamer/*) и используют базовый URL из соответствующей переменной окружения (см. config/config.go). Большинство клиентов построены на go-resty/resty (метод SetHostURL/SetBaseURL), часть — на внутренних http-обёртках gitlab.sarex.io/platform/gotools. Итоговый URL = <базовый URL сервиса> + путь из клиента.
Аутентификация исходящих запросов:
- к Sarex backend (Django) — HTTP Basic (
DJANGO_BASIC_AUTH, а для получения пользователей — DJANGO_BASIC_AUTH_FOR_GET_USER); для части ручек проксируется заголовок Identity/Bearer;
- к остальным сервисам — по внутренней сети кластера, как правило без внешней авторизации.
Базовые URL по сервисам
| Сервис |
Переменная окружения |
Клиент (каталог) |
| Sarex backend (Django) |
DJANGO_HOST |
clients/django, pkg/django, pkg/users, pkg/sarex_backend, clients/accounts |
| Flows |
FLOWS_URL |
pkg/flows |
| Workflows |
WORKFLOW_URL |
clients/workflow, pkg/workflows |
| Workspaces |
WORKSPACE_URL |
clients/workspace |
| Transmittals |
TRANSMITTALS_BASE_URL (опц.) |
pkg/transmittal |
| Automation |
AUTOMATION_URL |
pkg/automation |
| Marks (штампы, HTTP) |
MARKS_PROCESSING_URL |
pkg/marks/base |
| Marks (штампы, RabbitMQ) |
MARKS_RABBITMQ_* |
pkg/marks/rpc |
| BIM-API v1 |
BIM_API_URL |
clients/bim-api |
| BIM-API v2 (bim-core-api) |
BIM_API_V2_URL |
clients/bim-api-v2 |
| System log |
SYSTEM_LOG_URL |
pkg/system_log |
Дополнительно сервис работает с S3 (объектное хранилище, креды из S3_SERVICE_ACCOUNT/S3_SERVICE_ACCOUNT_STR) и PostgreSQL — это не HTTP-сервисы и в таблицах ниже не приводятся.
Эндпоинты по сервисам
Sarex backend (Django) — DJANGO_HOST
| Метод |
Путь |
Клиент |
Назначение |
| GET |
/api/core/users/ |
clients/django/users.go |
Список пользователей |
| GET |
/api/core/users/{id}/ |
clients/django/users.go, pkg/users/client.go |
Пользователь по id |
| GET |
/api/core/users/{id}/introspect |
clients/django/users.go |
Интроспекция пользователя |
| GET |
/api/core/users/{id} |
pkg/django/client.go |
Пользователь по id (внутренний клиент) |
| GET |
/api/client/settings/ |
clients/django/settings.go |
Клиентские настройки |
| GET |
/api/core/service-accounts/personalized/ |
clients/django/settings.go |
Персонализированные сервисные аккаунты |
| GET |
/api/core/service_accounts/ |
clients/django/service_accounts.go, clients/accounts |
Сервисные аккаунты |
| GET |
/api/core/companies/ |
clients/django/companies.go |
Список компаний |
| GET |
/api/core/mrpa/{id}/ |
pkg/sarex_backend/client.go |
MRPA по id (прокидывается заголовок Identity) |
Flows — FLOWS_URL
| Метод |
Путь |
Клиент |
Назначение |
| GET |
internal/v1/documents/?full=true&document_ids={id} |
pkg/flows/client.go |
Документы в процессах (flows) по id |
| GET/POST |
internal/v1/documents/ |
pkg/flows/client.go |
Документы процессов |
Workflows — WORKFLOW_URL
| Метод |
Путь |
Клиент |
Назначение |
| POST |
internal/v1/companies/{company_id}/workflows |
clients/workflow/client.go |
Создать workflow обработки (BIM/PDF/DWG/DEM/DOCX и т. д.); образы задач — из CONTAINER_REGISTRY + WORKFLOWS_IMAGES_VERSION |
| GET |
v1/workflows/{id} |
pkg/workflows/client.go |
Прочитать workflow по id |
Workspaces — WORKSPACE_URL
| Метод |
Путь |
Клиент |
Назначение |
| POST |
internal/v2/workspaces |
clients/workspace/client.go |
Создать воркспейс |
| DELETE |
internal/v2/documents/{ids} |
clients/workspace/client.go |
Удалить документы воркспейса |
| PATCH |
internal/v2/documents/restore |
clients/workspace/client.go |
Восстановить документы воркспейса |
Transmittals — TRANSMITTALS_BASE_URL
Клиент создаётся только если переменная задана.
| Метод |
Путь |
Клиент |
Назначение |
| POST |
/internal/v1/transmittals/by_bundle_ids |
pkg/transmittal/client.go |
Трансмитталы по списку bundle-id |
Automation — AUTOMATION_URL
| Метод |
Путь |
Клиент |
Назначение |
| — |
/internal/v1/automations/{process_name} |
pkg/automation/client.go |
Запуск/получение автоматизации по имени процесса |
Marks (штампы/маркировки)
Режим выбирается флагом USE_MARKS_RABBITMQ.
| Метод |
Путь / транспорт |
Клиент |
Назначение |
| POST |
/api/v1/marks/{bundle_id} (HTTP, MARKS_PROCESSING_URL) |
pkg/marks/base/client.go |
Наложение штампов на бандл (HTTP-режим) |
| — |
RabbitMQ (MARKS_RABBITMQ_*) |
pkg/marks/rpc |
Наложение штампов через очередь (RPC-режим, не HTTP) |
BIM-API v1 — BIM_API_URL
| Метод |
Путь |
Клиент |
Назначение |
| POST |
/internal/v1/targets/{target_id}/bims-pdm |
clients/bim-api/client.go |
Создать BIM для target (PDM) |
| POST |
/internal/v1/targets/{target_id}/bims-v2-pdm |
clients/bim-api/client.go |
Создать BIM v2 для target (PDM) |
BIM-API v2 (bim-core-api) — BIM_API_V2_URL
| Метод |
Путь |
Клиент |
Назначение |
| POST |
/internal/v1/projects/{project_id}/bims |
clients/bim-api-v2/client.go |
Создать BIM для проекта |
System log — SYSTEM_LOG_URL
| Метод |
Путь |
Клиент |
Назначение |
| POST |
/api/v0/system_log |
pkg/system_log/client.go |
Отправить запись в системный лог |
Обработка ошибок
Клиенты, как правило, проверяют код ответа и оборачивают ошибку через github.com/rotisserie/eris (напр. «invalid response code %d expected 200»). Для случая недоступности исходного сервиса в самом API определён нестандартный статус 523 (network/consts.go, StatusOriginIsUnreachable).
