Перейти к содержанию

Обзор API

Всё, что умеет интерфейс Аэрозвено, доступно через REST API gateway: поставить расчёт в очередь, следить за прогрессом, забрать план, выгрузить KML/GeoJSON и проверить любой план валидатором.

Параметр Значение
Базовый адрес стенда https://app.aerozveno.ru (доступ по логину и паролю, выдаются по запросу)
Формат JSON; поля документов сценария и плана — snake_case
Интерактивное описание Swagger UI /api/docs, спецификация OpenAPI /api/openapi.json
Размер тела запроса до 25 МБ
Ограничение частоты 100 запросов в минуту с одного адреса
Трассировка заголовок x-request-id (передаётся во внутренние сервисы)

Три шага: сценарий → план → файл

BASE=https://app.aerozveno.ru
AUTH="-u $LOGIN:$PASSWORD"

# 1. Поставить расчёт демо-сценария в очередь → 202 и planId
PLAN_ID=$(curl -sS $AUTH -X POST "$BASE/api/plans" \
  -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"scenario_id":"s03-multi-sites","objective":"makespan","time_limit_s":30}' | jq -r .planId)

# 2. Дождаться завершения: поток SSE или опрос
curl -sN $AUTH -H 'Accept: text/event-stream' "$BASE/api/plans/$PLAN_ID/events"
curl -sS $AUTH "$BASE/api/plans/$PLAN_ID" | jq '.status, .metrics'

# 3. Выгрузить KML и GeoJSON
curl -sS $AUTH -o plan.kml     "$BASE/api/plans/$PLAN_ID/export/kml"
curl -sS $AUTH -o plan.geojson "$BASE/api/plans/$PLAN_ID/export/geojson"

Проверить план валидатором:

curl -sS $AUTH "$BASE/api/scenarios/s03-multi-sites" > scenario.json
curl -sS $AUTH "$BASE/api/plans/$PLAN_ID" | jq .plan > plan.json
jq -n --slurpfile s scenario.json --slurpfile p plan.json '{scenario:$s[0], plan:$p[0]}' \
  | curl -sS $AUTH -X POST "$BASE/api/validate" -H 'content-type: application/json' -d @- \
  | jq '.report.admitted, [.report.checks[] | select(.status!="pass") | .id]'

Жизненный цикл расчёта

stateDiagram-v2
  [*] --> queued: POST /api/plans → 202
  queued --> running: gateway взял задание
  queued --> failed: POST …/stop (плана нет)
  running --> completed: план готов
  running --> failed: ошибка или нерешаемо
  running --> completed: POST …/stop → лучший найденный план
  completed --> [*]
  failed --> [*]

Пока статус не completed, поля plan в ответе нет, а выгрузка возвращает 409 PLAN_NOT_READY.

Разделы