Интерфейс к 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",
  "gitDockerfileURL": "https://github.com/user/dockerfiles.git",
  "gitDockerfileBranch": "master",
  "image_path": "registry.example.org/project/image",
  "registry_creds": "registry-login:registry-password",
  "config_path": "/path/to/config.yaml",
  "buildDockerfilePath": "images/app/Dockerfile",
  "buildContextPath": ".",
  "annotations": {
    "org.opencontainers.image.source": "https://github.com/user/repo",
    "org.opencontainers.image.version": "1.0.0"
  },
  "testEntrypoints": {
    "amd64": [["rpm", "--eval", "%_host_cpu"]],
    "all": [["nginx", "-v"]]
  }
}

Поля:

Правила расположения Dockerfile и context:

gitDockerfileBranch зависит от gitDockerfileURL: branch без URL невалиден. buildContextPath не зависит от gitDockerfileURL и никогда не указывает на Dockerfile-репозиторий.

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

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

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

{"detail": "Invalid request data"}

При ошибке валидации API может вернуть уточнение, например:

{"detail": "Invalid request data: annotations contains reserved key 'org.altlinux.altflow.builder'"}

{"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": "12h",
  "limit": "2000",
  "direction": "forward",
  "format": "text"
}

Поля:

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

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

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

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