115 lines
8.0 KiB
Markdown
115 lines
8.0 KiB
Markdown
# Эндпоинты внешних сервисов, с которыми взаимодействует 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`).
|