Версия: 2.0 (WIP)

API для внешних систем

Введение

Назначение

API CMDB предназначено для взаимодействия с внешними системами и обеспечивает следующие возможности:

получение атрибутов конфигурационных единиц (КЕ/CI);
поиск КЕ через TQL‑запросы в виде графа;
получение КЕ в виде дерева по заранее настроенным запросам.

Целевая аудитория

Интеграторы, разработчики внешних систем, DevOps/SRE, которые используют CMDB как источник данных.

Термины и сокращения

CMDB (Configuration Management Database) - база данных, которая используется в управлении ИТ-услугами (ITSM) для хранения информации обо всех значимых компонентах ИТ-инфраструктуры, их конфигурациях и взаимосвязях;
конфигурационная единица (КЕ/CI) - объект CMDB;
атрибут КЕ - свойство КЕ, например IP-адрес, операционная система, статус и т.д.;
TQL (Topology Query Language) - язык запросов для описания топологии графа. Он позволяет описывать различные свойства графов, такие как количество вершин и ребер, наличие циклов, связность и т.д.;
граф, дерево - настроенный и сохранённый в системе запрос.

Доступ к API

Базовый URL

Базовый URL для внешних систем https://<host>/v1/external/....

Аутентификация и авторизация

Для аутентификации и авторизации пользователей при подключении к системе Памир по URL для внешних систем используется уникальная шестнадцатеричная строка - API токен. Ограничения прав: существует разделение прав пользователей по типам КЕ, поэтому КЕ будут отфильтрованы в соответствии с назначенными правами.

Общие технические детали

Формат данных

Типы контента:

запросы/ответы: JSON;
кодировка: UTF‑8.

Обязательные заголовки:

Content-Type: application/json (для запросов с полезной нагрузкой).

Swagger / OpenAPI

Подробная техническая спецификация доступна в Swagger по ссылке https://<host>/api/srm/docs#/

Обработка ошибок

Общая схема ответа об ошибке содержит следующие ключи:

title: строка;
detail: строка;
errors: список списков строк;
type: строка.

Пример ошибки 404:

{
    "title": "Экземпляр 'SRMSearchQuery' not found",
    "detail": "",
    "errors": [
        [
            "ItemNotFoundError: Экземпляр 'SRMSearchQuery' not found",
            ""
        ]
    ],
    "type": "ItemNotFoundError"
}

Список типовых HTTP‑кодов:

200 — успех;
403 — проблемы с авторизацией/правами;
404 — запрос не найден;
422 — некорректный запрос (ошибка в теле, параметрах, TQL и т.п.);
500/503 — внутренние ошибки/недоступность сервиса.

При обработке ошибок пользователь внешних систем должен следовать следующей логике:

404/422 - исправить запрос;
403/500 - обратиться к поддержке;
503 - повторить запрос.

Пагинация и фильтрация

В ответах на запросы внешних систем пагинация не реализована, это нужно учитывать при обработке.

Описание групп функций и эндпоинтов

ci_public_v1 — атрибуты КЕ

Описание КЕ и атрибутов КЕ в контексте CMDB.

POST /v1/external/cis/attributes

Назначение: загрузка (чтение) указанных атрибутов для списка КЕ. Типичный кейс: по известным идентификаторам КЕ получить нужные поля. Формат запроса доступен в Swagger по адресу: https://<host>/api/srm/docs#/ci_public_v1/get_cis_attributes_v1_external_cis_attributes_post.

В запросе нужно указать:

cписок внутренних идентификаторов КЕ;
cписок названий атрибутов.

Если в списке есть несуществующие или недоступные КЕ, то в ответ они не войдут.

Пример запроса.

{
    "attr_names": ["jvm_version", "root_directory"],
    "ci_ids": ["dec104ad-ca88-4d01-be7f-8a0bc2845a82", "71051f85-79a7-48e5-93bc-d147bc33744e"]
}

Пример успешного ответа.

{
    "attributes": {
        "root_directory": "Корневая директория",
        "jvm_version": "Версия JVM",
        "name": "Название"
    },
    "values": [
        {
            "name": "CLMQM",
            "ci_id": "71051f85-79a7-48e5-93bc-d147bc33744e",
            "root_directory": "/opt/fesb/nfsmq"
        },
        {
            "name": "172.16.1.1:9696 (fesb-pamir-2)",
            "ci_id": "dec104ad-ca88-4d01-be7f-8a0bc2845a82",
            "jvm_version": "OpenJDK 64-Bit Server VM, 1.8.0_332 (JDK)"
        }
    ]
}

tql_v1 — поиск КЕ через TQL (граф)

Описание TQL

POST /v1/external/graph

Назначение: выполнение произвольного TQL‑запроса и получение результата в виде графа. Формат запроса доступен в Swagger по адресу: https://<host>/api/srm/docs#/tql_v1/get_ci_graph_v1_external_graph_post.

При синтаксической ошибке TQL поиск вернет пустые списки узлов и связей.

Пример запроса.

{
    "filter": {
        "cits": {
            "1": {
                "condition": "and",
                "matchers": [
                    {
                        "operator": "equals",
                        "target": "CIT_NAME",
                        "value": "fesb"
                    }
                ]
            }
        },
        "filter": {
            "condition": "one",
            "matchers": [
                "1"
            ]
        }
    },
    "include": []
}

Пример успешного ответа.

{
    "nodes": [
        {
            "ci_type_name": "fesb",
            "id": "3fbf5757-5f4a-4244-9779-dbe2c05b8c71",
            "ci_name": "172.16.1.2:9696 (fesb-pamir-1)"
        },
        {
            "ci_type_name": "fesb",
            "id": "dec104ad-ca88-4d01-be7f-8a0bc2845a82",
            "ci_name": "172.16.1.1:9696 (fesb-pamir-2)"
        }
    ],
    "links": []
}

GET /v1/external/graph/{query_name}

Назначение: Выполнение заранее сохранённого TQL‑запроса по имени query_name. Формат запроса доступен в Swagger по адресу: https://<host>/api/srm/docs#/tql_v1/get_ci_graph_by_query_name_v1_external_graph__query_name__get. Ответ аналогичен POST /v1/external/graph. Если имя запроса не существует в системе, то вернётся ошибка 404.

tree_v1 — получение КЕ в виде дерева

В отличие от графа иерархическое представление в виде дерева, удобно для навигации и отображения структур.

GET /v1/external/tree/{query_name}

Назначение: поиск и представление КЕ в виде дерева по имени query_name заранее сохранённого TQL-запроса. Формат запроса доступен в Swagger по адресу: https://<host>/api/srm/docs#/tree_v1/get_ci_tree_by_query_id_v1_external_tree__query_name__get. Если имя запроса не существует в системе вернётся пустой список. Пример успешного ответа.

[
    {
        "ci_type_name": "fesb",
        "node_id": "1",
        "ci_id": null,
        "ci_name": null,
        "children": [
            {
                "ci_type_name": "fesb",
                "node_id": "1",
                "ci_id": "dec104ad-ca88-4d01-be7f-8a0bc2845a82",
                "ci_name": "172.16.1.1:9696 (fesb-pamir-2)",
                "children": [
                    {
                        "ci_type_name": "menedzher_ocheredej",
                        "node_id": "2",
                        "ci_id": null,
                        "ci_name": null,
                        "children": [
                            {
                                "ci_type_name": "menedzher_ocheredej",
                                "node_id": "2",
                                "ci_id": "71051f85-79a7-48e5-93bc-d147bc33744e",
                                "ci_name": "CLMQM",
                                "children": []
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Нефункциональные аспекты

Идемпотентность

Все эндпоинты для внешних систем работают в режиме только для чтения.

Введение​

Назначение​

Целевая аудитория​

Термины и сокращения​

Доступ к API​

Базовый URL​

Аутентификация и авторизация​

Общие технические детали​

Формат данных​

Swagger / OpenAPI​

Обработка ошибок​

Пагинация и фильтрация​

Описание групп функций и эндпоинтов​

ci_public_v1 — атрибуты КЕ​

tql_v1 — поиск КЕ через TQL (граф)​

tree_v1 — получение КЕ в виде дерева​

Нефункциональные аспекты​

Идемпотентность​