Эндпоинты, с которыми взаимодействует documentations-api-v2
Документ описывает HTTP-эндпоинты внешних сервисов, к которым обращается Go-сервис documentation-api-v2 (pdm/documentation-api-v2).
Как устроено взаимодействие
Внешние вызовы выполняются типизированными клиентами в pkg/clients/* и pkg/django. Каждый клиент строится на github.com/go-resty/resty/v2 с SetBaseURL(<URL>), ретраями и (опционально) OTEL-трассировкой. Базовый URL берётся из переменной окружения (см. api-v2.CONFIGURATION.md); итоговый URL = <базовый URL> + путь, указанный в коде метода клиента.
Клиенты создаются в internal/api/httpserver/server.go (App.Run) и передаются в репозитории/юзкейсы. Аутентификация к внешним сервисам:
- Django и flows используют Basic-auth из
DJANGO_BASIC_AUTH;
- workspace (
Archive) пробрасывает пользовательский Bearer-токен (SetAuthToken);
- прочие внутренние сервисы вызываются по кластерным адресам без явной авторизации на уровне клиента.
Базовые адреса по сервисам
Клиент (pkg/...) |
Переменная базового URL |
Назначение |
django |
DJANGO_HOST |
Монолит/IAM: пользователи, компании, сервис-аккаунты, настройки |
clients/workspace |
WORKSPACE_URL |
Сервис рабочих областей |
clients/workflows |
WORKFLOW_URL |
Запуск workflow-обработки |
clients/bimv1 |
BIM_API_URL |
BIM API v1 |
clients/bimv2 |
BIM_API_V2_URL |
BIM API v2 (bim-core) |
clients/flows |
FLOWS_URL |
Сервис flows (процессы) |
clients/marks |
MARKS_PROCESSING_URL |
Сервис PDF-маркировок |
clients/system_log |
SYSTEM_LOG_URL |
Сервис журналирования |
Эндпоинты по сервисам
django — монолит/IAM (pkg/django)
| Метод |
Путь |
Назначение |
| GET |
api/client/settings/ |
Клиентские настройки |
| GET |
/api/core/companies/ |
Список компаний |
| GET |
/api/core/users/ |
Список пользователей |
| GET |
api/core/users/{user_id}/introspect |
Интроспекция пользователя |
| GET |
/api/core/service_accounts/ |
Сервис-аккаунты |
| GET |
/api/core/service-accounts/personalized/ |
Персонализированные сервис-аккаунты |
workspace — рабочие области (pkg/clients/workspace)
| Метод |
Путь |
Назначение |
| POST |
internal/v2/workspaces |
Создать рабочую область |
| DELETE |
internal/v2/documents/{document_ids} |
Удалить документы из рабочих областей; возвращает id опустевших областей |
| POST |
api/v1/workspaces/{workspace_id}/archive |
Архивировать рабочую область (с пользовательским Bearer-токеном) |
workflows — workflow-обработка (pkg/clients/workflows)
| Метод |
Путь |
Назначение |
| POST |
internal/v1/companies/{company_id}/workflows |
Создать/запустить workflow для компании |
bimv1 — BIM API v1 (pkg/clients/bimv1)
| Метод |
Путь |
Назначение |
| POST |
/internal/v1/targets/{target_id}/bims-pdm |
Зарегистрировать новый BIM (v1) |
| POST |
/internal/v1/targets/{target_id}/bims-v2-pdm |
Зарегистрировать новый BIM (v2) |
bimv2 — BIM API v2 (pkg/clients/bimv2)
| Метод |
Путь |
Назначение |
| POST |
/internal/v1/projects/{project_id}/bims |
Создать BIM в проекте |
flows — процессы (pkg/clients/flows)
| Метод |
Путь |
Назначение |
| GET |
api/v1/documents/?full=true&document_ids={id} |
Документы процессов по id |
marks — PDF-маркировки (pkg/clients/marks)
| Метод |
Путь |
Назначение |
| POST |
/api/v1/marks/{bundle_id} |
Массовое создание маркировок для бандла |
system_log — журналирование (pkg/clients/system_log)
| Метод |
Путь |
Назначение |
| POST |
/api/v0/system_log |
Отправка пакета записей журнала |
Обработка ошибок
Клиенты проверяют HTTP-статус ответа и при коде, отличном от ожидаемого (обычно 200), оборачивают ошибку через github.com/rotisserie/eris с указанием имени метода клиента (напр. bimapi.addNewBim: invalid response code %d expected 200). Транспортные ошибки resty также оборачиваются eris.Wrap. Настроены ретраи (напр. клиент workspace — 5 попыток с паузой 1 c, таймаут 10 c).
