# Справочники серверов vStack Serverspace API

> Проверьте локацию, допустимые CPU/RAM и совместимость образа с приложением до заказа vStack сервера.

- HTML: https://poapi.ru/serverspace/metainformatsiya-dlya-serverov
- Компания: Serverspace
- Страница компании: https://poapi.ru/company/serverspace
- Категории: Администрирование
- Сайт API: https://docs.serverspace.ru/docs/ru/
- Адрес API: https://api.serverspace.ru
- Документация: https://docs.serverspace.ru/docs/ru/

## Подключение и ограничения
- Авторизация: Для GET /api/v1/locations, /api/v1/images и /api/v1/applications нужен ключ проекта с VstackCloud/View (OAuth: vstack:view). Передавайте его в X-API-KEY; ключ создаётся в «Автоматизация» и ограничен проектом.
- Ограничения: /locations сообщает allow_creating_servers и допустимые CPU/RAM; false означает, что заказ сервера в локации сейчас отклонят. Значения 0 в лимитах диска/канала означают неопределённый предел. /images принимает location_id; /applications фильтруется по location_id и image_id. Это снимок доступных вариантов, не резерв и не проверка цены.

```bash
# Нужны bash, curl и jq. Передайте значения из плана заказа; пример ничего не заказывает.
set -euo pipefail
: "${SERVERSPACE_API_KEY:?Укажите ключ проекта}"
: "${LOCATION_ID:?Укажите ID локации}"
: "${CPU_CORES:?Укажите число CPU-ядер}"
: "${RAM_MB:?Укажите RAM в МБ}"
: "${OS_TYPE:?Укажите type из справочника образов, например Ubuntu}"
: "${OS_VERSION:?Укажите версию из справочника}"
: "${ARCHITECTURE:?Укажите architecture из справочника, например X64}"
: "${APPLICATION_ID:?Укажите id приложения из каталога}"
[[ "$CPU_CORES" =~ ^[1-9][0-9]*$ && "$RAM_MB" =~ ^[1-9][0-9]*$ ]] || { echo "CPU_CORES и RAM_MB должны быть положительными числами" >&2; exit 2; }
locations=$(curl --fail-with-body --silent --show-error --max-time 10 \
  --request GET --url "https://api.serverspace.ru/api/v1/locations" \
  --header "X-API-KEY: ${SERVERSPACE_API_KEY}") || exit 2
jq -e --arg id "$LOCATION_ID" --argjson cpu "$CPU_CORES" --argjson ram "$RAM_MB" \
  'any(.locations[]?; .id == $id and .allow_creating_servers == true and ((.cpu_quantity_options // []) | index($cpu) != null) and ((.ram_size_options // []) | index($ram) != null))' \
  <<<"$locations" >/dev/null || { echo "Локация закрыта или не поддерживает выбранные CPU/RAM" >&2; exit 1; }
images=$(curl --fail-with-body --silent --show-error --max-time 10 --get \
  --url "https://api.serverspace.ru/api/v1/images" \
  --header "X-API-KEY: ${SERVERSPACE_API_KEY}" \
  --data-urlencode "location_id=${LOCATION_ID}") || exit 2
image_id=$(jq -er --arg location "$LOCATION_ID" --arg type "$OS_TYPE" --arg version "$OS_VERSION" --arg arch "$ARCHITECTURE" \
  '[.images[]? | select(.location_id == $location and .type == $type and .os_version == $version and .architecture == $arch)] | if length == 1 then .[0].id else error("Нет единственного совпадающего образа") end' \
  <<<"$images") || { echo "Образ не найден или выбор неоднозначен" >&2; exit 1; }
applications=$(curl --fail-with-body --silent --show-error --max-time 10 --get \
  --url "https://api.serverspace.ru/api/v1/applications" \
  --header "X-API-KEY: ${SERVERSPACE_API_KEY}" \
  --data-urlencode "location_id=${LOCATION_ID}" \
  --data-urlencode "image_id=${image_id}") || exit 2
jq -e --arg app "$APPLICATION_ID" --arg image "$image_id" \
  'any(.applications[]?; .id == $app and ((.images // []) | index($image) != null))' \
  <<<"$applications" >/dev/null || { echo "Приложение недоступно для выбранного образа" >&2; exit 1; }
jq -c --arg app "$APPLICATION_ID" '{application: first(.applications[] | select(.id == $app)) | {id, recommended_cpu, recommended_ram_mb, recommended_storage_mb, parameters: [.parameters[]? | {name, required, secret}]}}' <<<"$applications"
echo "Локация, CPU/RAM, образ и приложение совместимы; сервер не создан."
```
- Результат: GET /api/v1/locations возвращает список locations; GET /api/v1/images — images; GET /api/v1/applications — applications. Пример выбирает ровно один образ и подтверждает, что приложение есть в выдаче по image_id и его images содержит выбранный образ. В конце он печатает recommended_* и только метаданные параметров; значения секретов и значения по умолчанию не выводятся. Код завершения 0 означает, что локация допускает заказ заданных CPU/RAM и приложение поддерживает выбранный образ; код завершения 1 — локация закрыта, конфигурация не поддерживается или образ/приложение отсутствует либо найден неоднозначный образ.
- Ошибки: Чтение требует VstackCloud/View. OpenAPI описывает 401 при отсутствующем/недействительном ключе и 403 при недостатке прав или области доступа; для /images и /applications также документирован 400 при неверном запросе. Код завершения 1 в примере — отсутствие поддерживаемой комбинации, код завершения 2 — HTTP- или сетевая ошибка или неверный числовой вход.
- Проверено по документации: 2026-11-15
- [Serverspace Public API v1 — справочник метаданных](https://docs.serverspace.ru/docs/ru/)
- [Serverspace Public API v1 — OpenAPI](https://docs.serverspace.ru/docs/ru/v1/openapi.json)
- [Тарификация и цены Serverspace](https://serverspace.ru/conditions/price/)

## Описание
Метаданные vStack помогают подготовить заказ сервера: получить доступные проекту локации и ограничения, выбрать образ ОС, затем проверить, доступно ли выбранное приложение для этой пары location id/image id. Каталоги не резервируют ресурсы и не создают сервер. VMware использует отдельные справочники.

## Собрать допустимую комбинацию для заказа

Предварительная проверка сначала выбирает локацию и проверяет текущий флаг allow_creating_servers, затем сверяет требуемое число ядер и RAM_MB с cpu_quantity_options и ram_size_options. Если любое условие не выполнено, следующий шаг — остановить заказ и выбрать другую конфигурацию.

По location_id каталог образов позволяет найти ровно один шаблон по типу ОС, os_version и architecture. Затем каталог applications запрашивается с той же локацией и найденным image_id; поле application.images подтверждает поддержку образа приложением. Сценарий не утверждает, что запрошенные CPU/RAM совпадают с рекомендациями приложения.

## Рекомендации — не цена и не резерв

Схема VstackApplication содержит recommended_cpu, recommended_ram_mb и recommended_storage_mb, а также параметры с признаками required и secret. Эти поля помогают подготовить форму заказа; пример выводит имена и признаки параметров, но не значения секретов или значения по умолчанию.

GET не резервирует ресурсы и не создаёт сервер. OpenAPI возвращает допустимые конфигурации и рекомендации, но не итоговую цену; тарифная страница сообщает об интервальной тарификации, а стоимость зависит от выбранных ресурсов и условий аккаунта.

## Когда использовать
- Перед заказом Linux-сервера проверьте, что в выбранной локации открыт заказ, CPU/RAM входят в список допустимых конфигураций, а нужное приложение поддерживает выбранный образ.
- Интерфейс заказа показывает рекомендованные CPU/RAM/диск и названия обязательных или секретных параметров приложения, не выводя значения секретов.

## Порядок интеграции
1. Подготовьте location_id, требуемые CPU и RAM, OS type/version/architecture и application_id из плана развертывания. Нужны curl и jq, ключ проекта с VstackCloud/View.
2. GET /api/v1/locations: проверьте allow_creating_servers и наличие CPU_CORES/RAM_MB в cpu_quantity_options/ram_size_options. Значение false закрывает заказ; 0 у пределов диска/канала означает «не определено».
3. GET /api/v1/images?location_id=... и найдите ровно один образ по type, os_version и architecture. Используйте его id в GET /api/v1/applications с location_id и image_id.
4. Убедитесь, что application_id есть в ответе и поле images включает выбранный image_id. Сценарий подтверждает доступность конфигурации локации и поддержку приложения выбранным образом; рекомендованные ресурсы и имена параметров выводятся отдельно. Заказ и установка требуют отдельного запроса.

## Что проверить перед запуском
- Справочники отражают доступные сейчас значения, но не резервируют локацию или конфигурацию; состояние может измениться до отправки заказа.
- CPU/RAM в location — списки допустимых размеров, рекомендуемые параметры приложения — отдельная подсказка, а не гарантия, что любой образ поместится на диск.
- Ответы не содержат цены для конкретного проекта/конфигурации. До заказа сверяйте актуальный тариф и применимые параметры в аккаунте; не выводите цену из recommended_* полей.

## Связанные API
- [Серверы vStack Serverspace](https://poapi.ru/serverspace/servery): API серверов vStack возвращает состояние и конфигурацию, рассчитывает месячную цену, создаёт и изменяет машины, а также удаляет ресурсы.
