Обзор REST API

Что такое REST API?

REST расшифровывается как representational state transfer (передача репрезентативного состояния). Это особый тип API, который использует HTTP-запросы и JavaScript Object Notation (JSON) для выполнения операций создания, получения, обновления и удаления (CRUD) над объектами в приложении. Каждый тип операции связан с определённым HTTP-глаголом:

GET: Получить объект или список объектов
POST: Создать объект
PUT / PATCH: Изменить существующий объект. PUT требует указания всех обязательных полей, тогда как PATCH ожидает только поле, которое изменяется.
DELETE: Удалить существующий объект

Кроме того, глагол OPTIONS может использоваться для проверки определённой точки REST API и возврата всех поддерживаемых действий и их доступных параметров.

Одним из основных преимуществ REST API является его дружественность к человеку. Поскольку он использует HTTP и JSON, очень легко взаимодействовать с данными InfraVision из командной строки с использованием общих инструментов. Например, мы можем запросить IP-адрес из InfraVision и вывести JSON, используя curl и jq. Следующая команда выполняет HTTP GET запрос для получения информации о конкретном IP-адресе, идентифицированном по его первичному ключу, и использует jq для представления возвращённых необработанных данных JSON в более удобочитаемом формате. (Передача вывода через jq не является строго обязательной, но делает его гораздо легче для чтения.)

curl -s http://netbox/api/ipam/ip-addresses/2954/ | jq '.'

{
  "id": 2954,
  "url": "http://netbox/api/ipam/ip-addresses/2954/",
  "family": {
    "value": 4,
    "label": "IPv4"
  },
  "address": "192.168.0.42/26",
  "vrf": null,
  "tenant": null,
  "status": {
    "value": "active",
    "label": "Active"
  },
  "role": null,
  "assigned_object_type": "dcim.interface",
  "assigned_object_id": 114771,
  "assigned_object": {
    "id": 114771,
    "url": "http://netbox/api/dcim/interfaces/114771/",
    "device": {
      "id": 2230,
      "url": "http://netbox/api/dcim/devices/2230/",
      "name": "router1",
      "display_name": "router1"
    },
    "name": "et-0/1/2",
    "cable": null,
    "connection_status": null
  },
  "nat_inside": null,
  "nat_outside": null,
  "dns_name": "",
  "description": "Example IP address",
  "tags": [],
  "custom_fields": {},
  "created": "2020-08-04",
  "last_updated": "2020-08-04T14:12:39.666885Z"
}

Каждый атрибут IP-адреса выражается как атрибут JSON-объекта. Поля могут включать собственные вложенные объекты, как в случае с полем assigned_object выше. Каждый объект включает первичный ключ с именем id, который уникально идентифицирует его в базе данных.

Интерактивная документация

Исчерпывающая интерактивная документация всех точек REST API доступна на работающем экземпляре InfraVision по адресу /api/schema/swagger-ui/. Этот интерфейс предоставляет удобную песочницу для исследования и экспериментов с конкретными точками и типами запросов. Сам API также можно исследовать с помощью веб-браузера, перейдя к его корню /api/.

Иерархия точек

Весь REST API InfraVision размещён под корнем API по адресу https://<hostname>/api/. Структура URL разделена на корневом уровне по приложениям: circuits, DCIM, extras, IPAM, plugins, tenancy, users и virtualization. Внутри каждого приложения существует отдельный путь для каждой модели. Например, объекты провайдеров и цепей находятся в приложении "circuits":

/api/circuits/providers/
/api/circuits/circuits/

Аналогично, объекты площадок, стоек и устройств находятся в приложении "DCIM":

/api/dcim/sites/
/api/dcim/racks/
/api/dcim/devices/

Полную иерархию доступных точек можно просмотреть, перейдя к корню API в веб-браузере.

Каждая модель обычно имеет два представления, связанных с ней: представление списка и детальное представление. Представление списка используется для получения списка нескольких объектов и создания новых объектов. Детальное представление используется для получения, обновления или удаления одного существующего объекта. Все объекты ссылаются по их числовому первичному ключу (id).

/api/dcim/devices/ - Список существующих устройств или создание нового устройства
/api/dcim/devices/123/ - Получить, обновить или удалить устройство с ID 123

Списки объектов могут быть отфильтрованы и упорядочены с использованием набора параметров запроса. Например, чтобы найти все интерфейсы, принадлежащие устройству с ID 123:

GET /api/dcim/interfaces/?device_id=123

Опциональный параметр ordering может использоваться для определения способа сортировки результатов. Развивая предыдущий пример, для сортировки всех интерфейсов в обратном порядке создания (от новых к старым) для устройства с ID 123:

GET /api/dcim/interfaces/?device_id=123&ordering=-created

См. документацию по фильтрации для получения более подробной информации о темах, связанных с фильтрацией, упорядочиванием и выражениями поиска.

Сериализация

REST API обычно представляет объекты одним из двух способов: полным или кратким. Базовый сериализатор используется для представления полного вида объекта. Это включает все поля таблицы базы данных, которые составляют модель, и может включать дополнительные метаданные. Базовый сериализатор включает связи с родительскими объектами, но не включает дочерние объекты. Например, VLANSerializer включает вложенное представление своей родительской группы VLAN (если есть), но не включает никаких назначенных префиксов. Сериализаторы используют минимальное "краткое" представление связанных объектов, которое включает только атрибуты, подходящие для идентификации объекта.

{
    "id": 1048,
    "site": {
        "id": 7,
        "url": "http://netbox/api/dcim/sites/7/",
        "name": "Corporate HQ",
        "slug": "corporate-hq"
    },
    "group": {
        "id": 4,
        "url": "http://netbox/api/ipam/vlan-groups/4/",
        "name": "Production",
        "slug": "production"
    },
    "vid": 101,
    "name": "Users-Floor1",
    "tenant": null,
    "status": {
        "value": 1,
        "label": "Active"
    },
    "role": {
        "id": 9,
        "url": "http://netbox/api/ipam/roles/9/",
        "name": "User Access",
        "slug": "user-access"
    },
    "description": "",
    "display_name": "101 (Users-Floor1)",
    "custom_fields": {}
}

Связанные объекты

Связанные объекты (например, поля ForeignKey) включаются с использованием вложенных кратких представлений. Это минимальное представление объекта, включающее только его прямой URL и достаточно информации для отображения объекта пользователю. При выполнении операций записи API (POST, PUT и PATCH) связанные объекты могут быть указаны либо по числовому ID (первичному ключу), либо по набору атрибутов, достаточно уникальных для возврата желаемого объекта.

Например, при создании нового устройства его стойка может быть указана по ID InfraVision (PK):

{
    "name": "MyNewDevice",
    "rack": 123,
    ...
}

Или по набору атрибутов, которые уникально идентифицируют стойку:

{
    "name": "MyNewDevice",
    "rack": {
        "site": {
            "name": "Equinix DC6"
        },
        "name": "R204"
    },
    ...
}

Обратите внимание, что если предоставленные параметры не возвращают ровно один объект, возникает ошибка валидации.

Обобщённые связи

Некоторые объекты в InfraVision имеют атрибуты, которые могут ссылаться на объект нескольких типов, известные как обобщённые связи. Например, IP-адрес может быть назначен либо интерфейсу устройства, либо интерфейсу виртуальной машины. При выполнении этого назначения через REST API мы должны указать два атрибута:

assigned_object_type - Тип содержимого назначенного объекта, определённый как <app>.<model>
assigned_object_id - Уникальный числовой ID назначенного объекта

Вместе эти значения идентифицируют уникальный объект в InfraVision. Назначенный объект (если есть) представлен атрибутом assigned_object в модели IP-адреса.

curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
http://netbox/api/ipam/ip-addresses/ \
--data '{
    "address": "192.0.2.1/24",
    "assigned_object_type": "dcim.interface",
    "assigned_object_id": 69023
}'

{
    "id": 56296,
    "url": "http://netbox/api/ipam/ip-addresses/56296/",
    "assigned_object_type": "dcim.interface",
    "assigned_object_id": 69000,
    "assigned_object": {
        "id": 69000,
        "url": "http://netbox/api/dcim/interfaces/69023/",
        "device": {
            "id": 2174,
            "url": "http://netbox/api/dcim/devices/2174/",
            "name": "device105",
            "display_name": "device105"
        },
        "name": "ge-0/0/0",
        "cable": null,
        "connection_status": null
    },
    ...
}

Если бы мы хотели назначить этот IP-адрес интерфейсу виртуальной машины вместо этого, мы бы установили assigned_object_type в virtualization.vminterface и соответственно обновили ID объекта.

Краткий формат

Большинство точек API поддерживают опциональный "краткий" формат, который возвращает только минимальное представление каждого объекта в ответе. Это полезно, когда вам нужен только список доступных объектов без связанных данных, например, при заполнении выпадающего списка в форме. В качестве примера, формат по умолчанию (полный) префикса выглядит так:

GET /api/ipam/prefixes/13980/

{
    "id": 13980,
    "url": "http://netbox/api/ipam/prefixes/13980/",
    "display_url": "http://netbox/api/ipam/prefixes/13980/",
    "display": "192.0.2.0/24",
    "family": {
        "value": 4,
        "label": "IPv4"
    },
    "prefix": "192.0.2.0/24",
    "vrf": null,
    "scope_type": "dcim.site",
    "scope_id": 3,
    "scope": {
        "id": 3,
        "url": "http://netbox/api/dcim/sites/3/",
        "display": "Site 23A",
        "name": "Site 23A",
        "slug": "site-23a",
        "description": ""
    },
    "tenant": null,
    "vlan": null,
    "status": {
        "value": "container",
        "label": "Container"
    },
    "role": {
        "id": 17,
        "url": "http://netbox/api/ipam/roles/17/",
        "name": "Staging",
        "slug": "staging"
    },
    "is_pool": false,
    "mark_utilized": false,
    "description": "Example prefix",
    "comments": "",
    "tags": [],
    "custom_fields": {},
    "created": "2025-03-01T20:01:23.458302Z",
    "last_updated": "2025-03-01T20:02:46.173540Z",
    "children": 0,
    "_depth": 0
}

Краткий формат гораздо более лаконичен:

GET /api/ipam/prefixes/13980/?brief=1

{
    "id": 13980,
    "url": "http://netbox/api/ipam/prefixes/13980/",
    "display": "192.0.2.0/24",
    "family": {
        "value": 4,
        "label": "IPv4"
    },
    "prefix": "192.0.2.0/24",
    "description": "Example prefix",
    "_depth": 0
}

Краткий формат поддерживается как для списков, так и для отдельных объектов.

Исключение контекстов конфигурации

При получении устройств и виртуальных машин через REST API каждый из них по умолчанию будет включать свои отрендеренные данные контекста конфигурации. Пользователи с большими объёмами контекстных данных, вероятно, заметят неоптимальную производительность при возврате нескольких объектов, особенно при очень больших размерах страниц. Чтобы справиться с этим, контекстные данные могут быть исключены из данных ответа путём прикрепления параметра запроса ?exclude=config_context к запросу. Этот параметр работает как для представлений списка, так и для детальных представлений.

Пагинация

Ответы API, содержащие список множества объектов, будут пагинированы для эффективности. Корневой JSON-объект, возвращаемый точкой списка, содержит следующие атрибуты:

count: Общее количество всех объектов, соответствующих запросу
next: Гиперссылка на следующую страницу результатов (если применимо)
previous: Гиперссылка на предыдущую страницу результатов (если применимо)
results: Список объектов на текущей странице

Вот пример пагинированного ответа:

HTTP 200 OK
Allow: GET, POST, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "count": 2861,
    "next": "http://netbox/api/dcim/devices/?limit=50&offset=50",
    "previous": null,
    "results": [
        {
            "id": 231,
            "name": "Device1",
            ...
        },
        {
            "id": 232,
            "name": "Device2",
            ...
        },
        ...
    ]
}

Страница по умолчанию определяется параметром конфигурации PAGINATE_COUNT, который по умолчанию равен 50. Однако это может быть переопределено для каждого запроса путём указания желаемых параметров запроса offset и limit. Например, если вы хотите получать сто устройств за раз, вы бы сделали запрос на:

http://netbox/api/dcim/devices/?limit=100

Ответ вернёт устройства с 1 по 100. URL, указанный в атрибуте next ответа, вернёт устройства с 101 по 200:

{
    "count": 2861,
    "next": "http://netbox/api/dcim/devices/?limit=100&offset=100",
    "previous": null,
    "results": [...]
}

Максимальное количество объектов, которые могут быть возвращены, ограничено параметром конфигурации MAX_PAGE_SIZE, который по умолчанию равен 1000. Установка его в 0 или None удалит максимальный лимит. Потребитель API может затем передать ?limit=0 для получения всех соответствующих объектов одним запросом.

Внимание

Отключение лимита размера страницы создаёт потенциал для очень ресурсоёмких запросов, поскольку один API-запрос может эффективно получить всю таблицу из базы данных.

Взаимодействие с объектами

Получение нескольких объектов

Чтобы запросить у InfraVision список объектов, сделайте GET запрос к точке списка модели. Объекты перечислены в параметре results объекта ответа.

curl -s -X GET http://netbox/api/ipam/ip-addresses/ | jq '.'

{
  "count": 42031,
  "next": "http://netbox/api/ipam/ip-addresses/?limit=50&offset=50",
  "previous": null,
  "results": [
    {
      "id": 5618,
      "address": "192.0.2.1/24",
      ...
    },
    {
      "id": 5619,
      "address": "192.0.2.2/24",
      ...
    },
    {
      "id": 5620,
      "address": "192.0.2.3/24",
      ...
    },
    ...
  ]
}

Получение одного объекта

Чтобы запросить у InfraVision один объект, сделайте GET запрос к детальной точке модели, указав её уникальный числовой ID.

Примечание

Обратите внимание, что завершающая косая черта обязательна. Её пропуск вернёт перенаправление 302.

curl -s -X GET http://netbox/api/ipam/ip-addresses/5618/ | jq '.'

{
  "id": 5618,
  "address": "192.0.2.1/24",
  ...
}

Создание нового объекта

Чтобы создать новый объект, сделайте POST запрос к точке списка модели с JSON-данными, относящимися к создаваемому объекту. Обратите внимание, что токен REST API требуется для всех операций записи; см. раздел аутентификация для получения дополнительной информации. Также убедитесь, что установлен HTTP-заголовок Content-Type в значение application/json.

curl -s -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/ipam/prefixes/ \
--data '{"prefix": "192.0.2.0/24", "scope_type": "dcim.site", "scope_id": 6}' | jq '.'

{
  "id": 18691,
  "url": "http://netbox/api/ipam/prefixes/18691/",
  "display_url": "http://netbox/api/ipam/prefixes/18691/",
  "display": "192.0.2.0/24",
  "family": {
    "value": 4,
    "label": "IPv4"
  },
  "prefix": "192.0.2.0/24",
  "vrf": null,
  "scope_type": "dcim.site",
  "scope_id": 6,
  "scope": {
    "id": 6,
    "url": "http://netbox/api/dcim/sites/6/",
    "display": "US-East 4",
    "name": "US-East 4",
    "slug": "us-east-4",
    "description": ""
  },
  "tenant": null,
  "vlan": null,
  "status": {
    "value": "active",
    "label": "Active"
  },
  "role": null,
  "is_pool": false,
  "mark_utilized": false,
  "description": "",
  "comments": "",
  "tags": [],
  "custom_fields": {},
  "created": "2025-04-29T15:44:47.597092Z",
  "last_updated": "2025-04-29T15:44:47.597092Z",
  "children": 0,
  "_depth": 0
}

Создание нескольких объектов

Чтобы создать несколько экземпляров модели одним запросом, сделайте POST запрос к точке списка модели со списком JSON-объектов, представляющих каждый создаваемый экземпляр. В случае успеха ответ будет содержать список вновь созданных экземпляров. Пример ниже иллюстрирует создание трёх новых площадок.

curl -X POST -H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
http://netbox/api/dcim/sites/ \
--data '[
{"name": "Site 1", "slug": "site-1", "region": {"name": "United States"}},
{"name": "Site 2", "slug": "site-2", "region": {"name": "United States"}},
{"name": "Site 3", "slug": "site-3", "region": {"name": "United States"}}
]'

[
    {
        "id": 21,
        "url": "http://netbox/api/dcim/sites/21/",
        "name": "Site 1",
        ...
    },
    {
        "id": 22,
        "url": "http://netbox/api/dcim/sites/22/",
        "name": "Site 2",
        ...
    },
    {
        "id": 23,
        "url": "http://netbox/api/dcim/sites/23/",
        "name": "Site 3",
        ...
    }
]

Обновление объекта

Чтобы изменить уже созданный объект, сделайте PATCH запрос к детальной точке модели, указав её уникальный числовой ID. Включите любые данные, которые вы хотите обновить на объекте. Как и при создании объекта, заголовки Authorization и Content-Type также должны быть указаны.

curl -s -X PATCH \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/ipam/prefixes/18691/ \
--data '{"status": "reserved"}' | jq '.'

{
  "id": 18691,
  "url": "http://netbox/api/ipam/prefixes/18691/",
  "display_url": "http://netbox/api/ipam/prefixes/18691/",
  "display": "192.0.2.0/24",
  "family": {
    "value": 4,
    "label": "IPv4"
  },
  "prefix": "192.0.2.0/24",
  "vrf": null,
  "scope_type": "dcim.site",
  "scope_id": 6,
  "scope": {
    "id": 6,
    "url": "http://netbox/api/dcim/sites/6/",
    "display": "US-East 4",
    "name": "US-East 4",
    "slug": "us-east-4",
    "description": ""
  },
  "tenant": null,
  "vlan": null,
  "status": {
    "value": "reserved",
    "label": "Reserved"
  },
  "role": null,
  "is_pool": false,
  "mark_utilized": false,
  "description": "",
  "comments": "",
  "tags": [],
  "custom_fields": {},
  "created": "2025-04-29T15:44:47.597092Z",
  "last_updated": "2025-04-29T15:49:40.689109Z",
  "children": 0,
  "_depth": 0
}

PUT против PATCH

REST API InfraVision поддерживает использование как PUT, так и PATCH для изменения существующего объекта. Разница в том, что запрос PUT требует от пользователя указания полного представления изменяемого объекта, тогда как запрос PATCH должен включать только атрибуты, которые обновляются. Для большинства целей рекомендуется использовать PATCH.

Обновление нескольких объектов

Несколько объектов могут быть обновлены одновременно путём отправки запроса PUT или PATCH к точке списка модели со списком словарей, указывающих числовой ID каждого объекта для удаления и атрибуты для обновления. Например, чтобы обновить площадки с ID 10 и 11 до статуса "active", выполните следующий запрос:

curl -s -X PATCH \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/dcim/sites/ \
--data '[{"id": 10, "status": "active"}, {"id": 11, "status": "active"}]'

Обратите внимание, что нет требования, чтобы атрибуты были идентичны среди объектов. Например, можно обновить статус одной площадки вместе с именем другой в одном запросе.

Примечание

Массовое обновление объектов является операцией "всё или ничего", что означает, что если InfraVision не удастся успешно обновить любой из указанных объектов (например, из-за ошибки валидации), вся операция будет прервана и ни один из объектов не будет обновлён.

Удаление объекта

Чтобы удалить объект из InfraVision, сделайте DELETE запрос к детальной точке модели, указав её уникальный числовой ID. Заголовок Authorization должен быть включён для указания токена авторизации, однако этот тип запроса не поддерживает передачу каких-либо данных в теле.

curl -s -X DELETE \
-H "Authorization: Token $TOKEN" \
http://netbox/api/ipam/prefixes/18691/

Обратите внимание, что запросы DELETE не возвращают никаких данных: В случае успеха API вернёт ответ 204 (No Content).

Примечание

Вы можете запустить curl с флагом verbose (-v) для проверки кодов HTTP-ответа.

Удаление нескольких объектов

InfraVision поддерживает одновременное удаление нескольких объектов одного типа путём отправки DELETE запроса к точке списка модели со списком словарей, указывающих числовой ID каждого объекта для удаления. Например, чтобы удалить площадки с ID 10, 11 и 12, выполните следующий запрос:

curl -s -X DELETE \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/dcim/sites/ \
--data '[{"id": 10}, {"id": 11}, {"id": 12}]'

Примечание

Массовое удаление объектов является операцией "всё или ничего", что означает, что если InfraVision не удастся удалить любой из указанных объектов (например, из-за зависимости от связанного объекта), вся операция будет прервана и ни один из объектов не будет удалён.

Сообщения журнала изменений

Информация

Эта функция была введена в InfraVision v4.4.

Большинство объектов в InfraVision поддерживают журналирование изменений, которое создаёт детальную запись каждый раз, когда объект создаётся, изменяется или удаляется. Начиная с InfraVision v4.4, пользователи также могут прикреплять сообщение к записи изменения. Это достигается через REST API путём включения поля changelog_message в представление объекта.

Например, следующий API-запрос создаст новую площадку и запишет сообщение в результирующую запись журнала изменений:

curl -s -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/dcim/sites/ \
--data '{
    "name": "Site A",
    "slug": "site-a",
    "changelog_message": "Добавление площадки для заявки #4137"
}'

Этот подход работает при создании, изменении или удалении объектов как индивидуально, так и массово.

Загрузка файлов

Поскольку JSON не поддерживает включение бинарных данных, файлы не могут быть загружены с использованием API-запросов в формате JSON. Вместо этого мы можем использовать кодирование данных формы для прикрепления локального файла.

Например, мы можем загрузить вложение изображения, используя команду curl, показанную ниже. Обратите внимание, что @ обозначает локальный файл на диске для загрузки.

curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-F "object_type=dcim.site" \
-F "object_id=2" \
-F "name=attachment1.png" \
-F "image=@local_file.png" \
http://netbox/api/extras/image-attachments/

Аутентификация

REST API InfraVision в основном использует аутентификацию на основе токенов. Для удобства также может использоваться аутентификация на основе cookie при навигации по просматриваемому API.

Токены

Токен — это уникальный идентификатор, сопоставленный с учётной записью пользователя InfraVision. Каждый пользователь может иметь один или несколько токенов, которые он может использовать для аутентификации при выполнении запросов REST API. Чтобы создать токен, перейдите на страницу токенов API в вашем профиле пользователя.

По умолчанию все пользователи могут создавать и управлять своими собственными токенами REST API в панели управления пользователя в интерфейсе или через REST API. Эту возможность можно отключить, переопределив параметр конфигурации DEFAULT_PERMISSIONS.

Каждый токен содержит 160-битный ключ, представленный как 40 шестнадцатеричных символов. При создании токена вы обычно оставляете поле ключа пустым, чтобы случайный ключ генерировался автоматически. Однако InfraVision позволяет вам указать ключ в случае, если вам нужно восстановить ранее удалённый токен в работу.

Кроме того, токен может быть настроен на истечение в определённое время. Это может быть полезно, если внешнему клиенту необходимо предоставить временный доступ к InfraVision.

Ограничение получения токена

Возможность получения значения ключа ранее созданного API-токена может быть ограничена путём отключения параметра конфигурации ALLOW_TOKEN_RETRIEVAL.

Ограничение операций записи

По умолчанию токен может использоваться для выполнения всех действий через API, которые пользователю было бы разрешено выполнять через веб-интерфейс. Снятие флажка "запись включена" ограничит API-запросы, сделанные с токеном, только операциями чтения (например, GET).

Ограничение IP клиента

Каждый API-токен может быть опционально ограничен по IP-адресу клиента. Если для токена определён один или несколько разрешённых IP-префиксов/адресов, аутентификация завершится неудачей для любого клиента, подключающегося с IP-адреса за пределами определённого диапазона(-ов). Это позволяет ограничить использование токена конкретным клиентом. (По умолчанию разрешён любой IP-адрес клиента.)

Создание токенов для других пользователей

Возможно создание токенов аутентификации для других пользователей через REST API. Для этого запрашивающий пользователь должен иметь назначенное разрешение users.grant_token. Хотя все пользователи по умолчанию имеют врождённое разрешение создавать свои собственные токены, это разрешение требуется для включения создания токенов для других пользователей.

Соблюдайте осторожность

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

Аутентификация в API

Токен аутентификации прикрепляется к запросу путём установки заголовка Authorization в строку Token, за которой следует пробел и токен пользователя:

$ curl -H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
https://{infravision}/api/dcim/sites/
{
    "count": 10,
    "next": null,
    "previous": null,
    "results": [...]
}

Токен не требуется для операций только для чтения, которые были освобождены от применения разрешений (с использованием параметра конфигурации EXEMPT_VIEW_PERMISSIONS). Однако если токен требуется, но не присутствует в запросе, API вернёт ответ 403 (Forbidden):

$ curl https://{infravision}/api/dcim/sites/
{
    "detail": "Authentication credentials were not provided."
}

Когда токен используется для аутентификации запроса, его время last_updated обновляется до текущего времени, если его последнее использование было записано более 60 секунд назад (или никогда не записывалось). Это позволяет пользователям определить, какие токены недавно были активны.

Примечание

Время "последнего использования" для токенов не будет обновляться, пока включён режим обслуживания.

Начальное предоставление токена

В идеале каждый пользователь должен создавать свои собственные API-токены через веб-интерфейс. Однако вы можете столкнуться со сценарием, когда токен должен быть создан пользователем через сам REST API. InfraVision предоставляет специальную точку для создания токенов с использованием действительной комбинации имени пользователя и пароля. (Обратите внимание, что пользователь должен иметь разрешение на создание API-токенов независимо от используемого интерфейса.)

Чтобы создать токен через REST API, сделайте POST запрос к точке /api/users/tokens/provision/:

$ curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
https://{infravision}/api/users/tokens/provision/ \
--data '{
    "username": "hankhill",
    "password": "I<3C3H8"
}'

Обратите внимание, что мы не передаём существующий REST API токен с этим запросом. Если предоставленные учётные данные действительны, новый REST API токен будет автоматически создан для пользователя. Обратите внимание, что ключ будет сгенерирован автоматически, и возможность записи будет включена.

{
    "id": 6,
    "url": "https://{infravision}/api/users/tokens/6/",
    "display_url": "https://{infravision}/api/users/tokens/6/",
    "display": "**********************************3c9cb9",
    "user": {
        "id": 2,
        "url": "https://{infravision}/api/users/users/2/",
        "display": "hankhill",
        "username": "hankhill"
    },
    "created": "2024-03-11T20:09:13.339367Z",
    "expires": null,
    "last_used": null,
    "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9",
    "write_enabled": true,
    "description": "",
    "allowed_ips": []
}

HTTP-заголовки

`API-Version`

Этот заголовок указывает используемую версию API. Она всегда будет соответствовать версии установленной InfraVision. Например, InfraVision v3.4.2 будет сообщать версию API 3.4.

`X-Request-ID`

Этот заголовок указывает уникальный ID, назначенный полученному API-запросу. Он может быть очень полезен для корреляции запроса с записями изменений. Например, после создания нескольких новых объектов вы можете отфильтровать точку API изменений объектов, чтобы получить результирующие записи изменений:

GET /api/extras/object-changes/?request_id=e39c84bc-f169-4d5f-bc1c-94487a1b18b5

ID запроса также может использоваться для фильтрации многих объектов напрямую, чтобы вернуть те, которые были созданы или обновлены определённым запросом:

GET /api/dcim/sites/?created_by_request=e39c84bc-f169-4d5f-bc1c-94487a1b18b5

Примечание

Этот заголовок включается во все ответы InfraVision, хотя он наиболее практичен при работе с API.