89 lines
5.7 KiB
Markdown
89 lines
5.7 KiB
Markdown
# Эндпоинты, с которыми взаимодействует documentations-api-v2
|
||
|
||
Документ описывает HTTP-эндпоинты внешних сервисов, к которым обращается Go-сервис **documentation-api-v2** (`pdm/documentation-api-v2`).
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
Внешние вызовы выполняются типизированными клиентами в `pkg/clients/*` и `pkg/django`. Каждый клиент строится на [`github.com/go-resty/resty/v2`](https://github.com/go-resty/resty) с `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).
|