REST API

Плагины могут объявлять пользовательские точки на REST API InfraVision для получения или манипулирования моделями или другими данными. Они ведут себя очень похоже на представления, за исключением того, что вместо отрисовки произвольного контента с использованием шаблона, данные возвращаются в формате JSON с использованием сериализатора.

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

Структура кода

Рекомендуемый подход — разделить сериализаторы API, представления и URL на отдельные модули в каталоге api/, чтобы поддерживать порядок, особенно для крупных проектов. Файл api/__init__.py может импортировать соответствующие компоненты из каждого подмодуля, чтобы позволить импортировать все компоненты API напрямую из другого места. Однако это лишь соглашение и не является строго обязательным.

project-name/
  - plugin_name/
    - api/
      - __init__.py
      - serializers.py
      - urls.py
      - views.py
    ...

Сериализаторы

Сериализаторы моделей

Сериализаторы отвечают за преобразование объектов Python в данные JSON, подходящие для передачи потребителям, и наоборот. InfraVision предоставляет класс NetBoxModelSerializer для использования плагинами для обработки назначения тегов и данных пользовательских полей. (Эти функции также могут быть включены отдельно через классы CustomFieldModelSerializer и TaggableModelSerializer.)

Вложенное представление объекта по умолчанию определяется атрибутом brief_fields в классе Meta сериализатора. (В старых версиях InfraVision требовалось определение отдельного вложенного сериализатора.)

Пример

Чтобы создать сериализатор для модели плагина, создайте подкласс NetBoxModelSerializer в api/serializers.py. Укажите класс модели и поля для включения в класс Meta сериализатора.

# api/serializers.py
from rest_framework import serializers
from netbox.api.serializers import NetBoxModelSerializer
from my_plugin.models import MyModel

class MyModelSerializer(NetBoxModelSerializer):
    foo = SiteSerializer(nested=True, allow_null=True)

    class Meta:
        model = MyModel
        fields = ('id', 'foo', 'bar', 'baz')
        brief_fields = ('id', 'url', 'display', 'bar')

Наборы представлений

Как и в пользовательском интерфейсе, представление REST API обрабатывает бизнес-логику отображения и взаимодействия с объектами InfraVision. InfraVision предоставляет класс NetBoxModelViewSet, который расширяет встроенный ModelViewSet DRF для обработки массовых операций и валидации объектов.

В отличие от пользовательского интерфейса, обычно требуется только один набор представлений на модель: этот набор представлений обрабатывает все типы запросов (GET, POST, DELETE и т.д.).

Пример

Чтобы создать набор представлений для модели плагина, создайте подкласс NetBoxModelViewSet в api/views.py и определите атрибуты queryset и serializer_class.

# api/views.py
from netbox.api.viewsets import NetBoxModelViewSet
from my_plugin.models import MyModel
from .serializers import MyModelSerializer

class MyModelViewSet(NetBoxModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer

Маршрутизаторы

Маршрутизаторы сопоставляют URL с представлениями REST API (точками). InfraVision не предоставляет каких-либо пользовательских компонентов для этого; класс DefaultRouter, предоставляемый DRF, должен быть достаточен для большинства случаев использования.

Маршрутизаторы должны быть объявлены в api/urls.py. Этот файл должен определять переменную с именем urlpatterns.

Пример

# api/urls.py
from netbox.api.routers import NetBoxRouter
from .views import MyModelViewSet

router = NetBoxRouter()
router.register('my-model', MyModelViewSet)
urlpatterns = router.urls

Это сделает представление плагина доступным по адресу /api/plugins/my-plugin/my-model/.

Внимание

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