Интерфейс к API

Документ описывает внешний HTTP-интерфейс компонентов altflow-api и altflow-api-lite. Все прикладные запросы отправляются в JSON. Основной префикс маршрутов: /api-v1.

altflow-api использует авторизацию через внешний identity provider и выдаёт внутренний токен Altflow. altflow-api-lite не имеет маршрутов /api-v1/auth/* и проверяет заранее настроенный статический bearer-токен.

Авторизация

Получение токена Altflow

Доступно только в altflow-api.

Метод: POST URL: /api-v1/auth/token

Заголовок:

Authorization: Bearer <identity-provider-token>

Успешный ответ:

{
  "access_token": "<altflow-token>",
  "refresh_token": null
}

Swagger UI использует отдельный callback route:

GET /api-v1/auth/docs

Запуск сборки

Метод: POST URL: /api-v1/build

Заголовок:

Authorization: Bearer <altflow-token>

Минимальный запрос:

{
  "image_arch": "amd64",
  "git_url": "https://github.com/user/repo.git",
  "image_path": "registry.example.org/project/image",
  "registry_creds": "login:password",
  "buildDockerfilePath": "./Dockerfile",
  "buildContextPath": "."
}

Полный запрос с опциональными полями:

{
  "image_arch": ["amd64", "arm64"],
  "image_tag": ["latest", "1.0.0"],
  "git_url": "https://github.com/user/repo.git",
  "git_creds": "git-login:git-password",
  "buildGitBranch": "master",
  "image_path": "registry.example.org/project/image",
  "registry_creds": "registry-login:registry-password",
  "config_path": "/path/to/config.yaml",
  "buildDockerfilePath": "./Dockerfile",
  "buildContextPath": ".",
  "testEntrypoints": [
    ["/app/altflow-tests/run"],
    ["nginx", "-v"]
  ]
}

Поля:

ПолеТипОбязательноеОписание
image_pathstringдаПуть в формате registry/image. Устаревший алиас: registry_name. Если в image_path указан тег через :, он добавляется в список тегов.
image_archstring или array[string]даАрхитектуры. Допустимые значения: amd64, x86_64, arm64, aarch64, 386, i586, loongarch64, riscv64. Значения нормализуются к amd64, arm64, i586, loongarch64, riscv64.
image_tagstring или array[string]нетДо 10 тегов. Строка может содержать теги через запятую. По умолчанию latest.
git_urlstringдаHTTPS URL Git-репозитория.
git_credsstringнетУчётные данные Git в формате login:password.
buildGitBranchstringнетВетка Git.
registry_credsstringдаУчётные данные пользовательского registry в формате login:password.
config_pathstringнетПуть к пользовательскому конфигурационному файлу.
buildDockerfilePathstringдаПуть к Dockerfile внутри Git-репозитория.
buildContextPathstringнетКонтекст сборки. Если поле пустое, API берёт каталог, в котором находится Dockerfile, либо ..
testEntrypointsarray[array[string]]нетКоманды стадии TEST. Если поле пустое или отсутствует, TEST пропускается.

Успешный ответ:

{
  "task_id": "01JBV2S4PGNV87EGC5WKYA0RND",
  "status": "queued"
}

Типовые ошибки:

{"detail": "Invalid request data"}

{"detail": "Unauthorized: the token is not valid"}

{"detail": "Unauthorized: the token has expired"}

Получение статуса сборки

Метод: GET URL: /api-v1/builds/{task_id}

Заголовок:

Authorization: Bearer <altflow-token>

API читает stateEvents в TrackDB и возвращает историю состояний по taskId, отсортированную по insertTime DESC.

Успешный ответ:

[
  {
    "eventTime": 1735678830,
    "eventStage": "BUILD",
    "eventStageState": "DONE",
    "user": "alexander"
  },
  {
    "eventTime": 1735678820,
    "eventStage": "BUILD",
    "eventStageState": "RUNNING",
    "user": "alexander"
  }
]

Если API уже выдал task_id, но TrackDB ещё не получил событие:

{
  "status": "processing",
  "warn": "TrackDB has not received the task yet. Please, try later or contact administrator"
}

Получение логов сборки

Метод: POST URL: /api-v1/logs

Заголовок:

Authorization: Bearer <altflow-token>

Запрос:

{
  "taskId": "01K5BYCRDA52QBGNTWX429JPDS",
  "eventStage": "BUILD",
  "start": "1758188000",
  "end": "1758188779",
  "since": "1h",
  "limit": "10",
  "direction": "backward",
  "format": "json"
}

Поля:

ПолеТипОбязательноеОписание
taskIdstringдаULID задачи.
eventStagestringнетОдин из BUILD, TEST, SIGN, PUSH, CLEANUP. Если не указан, API запрашивает логи всех стадий задачи.
startstringнетНачало интервала для Loki.
endstringнетКонец интервала для Loki.
sincestringнетОтносительный интервал; используется если не указан start.
limitstringнетЛимит записей. По умолчанию 100.
directionstringнетbackward или forward. По умолчанию backward.
formatstringнетjson или text. По умолчанию json.

API формирует Loki query по labels taskid и опционально eventStage, затем возвращает либо исходный JSON result, либо текстовые строки логов.

Служебные маршруты

GET /alive
GET /ready
GET /metrics
GET /docs/

/metrics возвращает Prometheus metrics. Доступ к нему защищён отдельной проверкой заголовка AUTH_METRICS, если она включена в middleware/deployment.