Общие сведения

Модуль «Сервисный каталог» продукта «Служба управления конфигурациями» предоставляет RESTful API для управления спецификациями политик и ПО в «Кабинете администратора», а также управления Salt-формулами.

API модуля «Сервисный каталог»

API-интерфейс модуля «Сервисный каталог» разбит на несколько библиотек согласно назначению операций:

  • Specifications — API для управления спецификациями конфигураций;

  • Formulas — API для управления формулами SaltStack.

Каталог Specifications

Каталог включает методы:

  • getFormulaById  — получение спецификации по идентификатору;

  • getFormulaList — получение списка спецификаций;

  • createFormula — создание (импорт) спецификации;

Метод getSpecificationById

Получение спецификации по идентификатору.

GET /v1/specifications/{specificationId}

Параметры пути
Имя Описание Обязательный Значение по умолчанию

specificationId

Идентификатор спецификации

Да

null
Тип контента

  • application/json

Ответы
Код Сообщение Тип данных Пример

200

Представление спецификации

FormulaSpecification

 
{
  "id": "5467",
  "formulaName": "yandex-browser",
  "displayName": "Яндекс браузер",
  "description": "Formula to install web browser developed by Yandex.",
  "stagesToComplete": [
    ""
  ],
  "pillarConfigName": "Formula to install web browser developed by Yandex.",
  "pillarProperties": [
    {
      "key": "yandex-browser.lookup.pkg.version",
      "value": "23.5.4.685-1",
      "description": "The specific version of the package. If value is an empty string, then will be used the latest version."
    }
  ]
}

400

Incorrect request params (некорректные параметры запроса)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

401

Auth exception (ошибка аутентификации)

404

Object not found (объект не найден)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

500

Internal error (внутренняя ошибка)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

Метод getSpecificationList

Получение списка спецификаций.

POST /v1/specifications/search

Параметры запроса
Имя Описание Обязательный Значение по умолчанию

page

Общее количество страниц

Нет

2

pageSize

Количество возвращаемых элементов в запросе

Нет

20
Пример запроса
{
  "displayName": "Яндекс браузер",
  "description": "Formula to install web browser developed by Yandex."
}
Тип контента

  • application/json

Ответы
Код Сообщение Тип данных Пример

200

Список спецификаций

FormulaSpecificationResponse

 
{
  "formulaSpecifications": [
    {
      "id": "5467",
      "formulaName": "yandex-browser",
      "displayName": "Яндекс браузер",
      "description": "Formula to install web browser developed by Yandex.",
      "stagesToComplete": [
        ""
      ],
      "pillarConfigName": "Formula to install web browser developed by Yandex.",
      "pillarProperties": [
        {
          "key": "yandex-browser.lookup.pkg.version",
          "value": "23.5.4.685-1",
          "description": "The specific version of the package. If value is an empty string, then will be used the latest version."
        }
      ]
    }
  ],
  "meta": {
    "totalRecords": 1729,
    "pageSize": 20,
    "totalPages": 87,
    "currentPage": 2,
    "hasNext": true,
    "hasPrev": true
  }
}

400

Incorrect request params (некорректные параметры запроса)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

401

Auth exception (ошибка аутентификации)

500

Internal error (внутренняя ошибка)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

Метод createSpecification

Создание спецификации.

POST /v1/specifications

Пример запроса
{
  "formulaName": "yandex-browser",
  "displayName": "Яндекс браузер",
  "description": "Formula to install web browser developed by Yandex.",
  "stagesToComplete": [
    ""
  ],
  "pillarConfigName": "Formula to install web browser developed by Yandex.",
  "pillarProperties": [
    {
      "key": "yandex-browser.lookup.pkg.version",
      "value": "23.5.4.685-1",
      "description": "The specific version of the package. If value is an empty string, then will be used the latest version."
    }
  ]
}
Тип контента

  • application/json

Ответы
Код Сообщение Тип данных Пример

200

Представление спецификации

FormulaSpecification

 
{
  "id": "5467",
  "formulaName": "yandex-browser",
  "displayName": "Яндекс браузер",
  "description": "Formula to install web browser developed by Yandex.",
  "stagesToComplete": [
    ""
  ],
  "pillarConfigName": "Formula to install web browser developed by Yandex.",
  "pillarProperties": [
    {
      "key": "yandex-browser.lookup.pkg.version",
      "value": "23.5.4.685-1",
      "description": "The specific version of the package. If value is an empty string, then will be used the latest version."
    }
  ]
}

400

Incorrect request params (некорректные параметры запроса)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

401

Auth exception (ошибка аутентификации)

404

Object not found (объект не найден)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

500

Internal error (внутренняя ошибка)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

Каталог Formulas

Каталог включает метод:

  • importFormulas — импорт Salt-формулы в хранилище S3.

Метод importFormulas

Импорт Salt-формулы в хранилище S3.

POST /v1/formulas

Параметры запроса
Имя Описание Обязательный Значение по умолчанию

formula

Файл с формулой

Контент архива должен соответствовать структуре формулы, которая задана в SaltStack, поэтому файл должен быть в формате <name>-formula.tar.gz.

Да
Тип контента

  • multipart/form-data

Ответы
Код Сообщение Тип данных Пример

200

Формула добавлена в S3

FormulaImportResult

 
{
  "ignoredFilesCount": 3,
  "errors": [
    "string"
  ]
}

401

Auth exception (ошибка аутентификации)

404

Object not found (объект не найден)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}

500

Internal error (внутренняя ошибка)

BasicError

 
{
  "code": "validation_failed",
  "message": "Template contains not resolved variables"
}