mirror of
https://github.com/netbox-community/netbox.git
synced 2024-05-10 07:54:54 +00:00
70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
# REST API
|
|
|
|
Plugins can declare custom endpoints on NetBox's REST API to retrieve or manipulate models or other data. These behave very similarly to views, except that instead of rendering arbitrary content using a template, data is returned in JSON format using a serializer.
|
|
|
|
Generally speaking, there aren't many NetBox-specific components to implementing REST API functionality in a plugin. NetBox employs the [Django REST Framework](https://www.django-rest-framework.org/) (DRF) for its REST API, and plugin authors will find that they can largely replicate the same patterns found in NetBox's implementation. Some brief examples are included here for reference.
|
|
|
|
## Serializers
|
|
|
|
Serializers are responsible for converting Python objects to JSON data suitable for conveying to consumers, and vice versa. NetBox provides the `NetBoxModelSerializer` class for use by plugins to handle the assignment of tags and custom field data. (These features can also be included ad hoc via the `CustomFieldModelSerializer` and `TaggableModelSerializer` classes.)
|
|
|
|
### Example
|
|
|
|
To create a serializer for a plugin model, subclass `NetBoxModelSerializer` in `api/serializers.py`. Specify the model class and the fields to include within the serializer's `Meta` class.
|
|
|
|
```python
|
|
# api/serializers.py
|
|
from netbox.api.serializers import NetBoxModelSerializer
|
|
from my_plugin.models import MyModel
|
|
|
|
class MyModelSerializer(NetBoxModelSerializer):
|
|
|
|
class Meta:
|
|
model = MyModel
|
|
fields = ('id', 'foo', 'bar')
|
|
```
|
|
|
|
## Viewsets
|
|
|
|
Just as in the user interface, a REST API view handles the business logic of displaying and interacting with NetBox objects. NetBox provides the `NetBoxModelViewSet` class, which extends DRF's built-in `ModelViewSet` to handle bulk operations and object validation.
|
|
|
|
Unlike the user interface, typically only a single view set is required per model: This view set handles all request types (`GET`, `POST`, `DELETE`, etc.).
|
|
|
|
### Example
|
|
|
|
To create a viewset for a plugin model, subclass `NetBoxModelViewSet` in `api/views.py`, and define the `queryset` and `serializer_class` attributes.
|
|
|
|
```python
|
|
# api/views.py
|
|
from netbox.api.viewsets import ModelViewSet
|
|
from my_plugin.models import MyModel
|
|
from .serializers import MyModelSerializer
|
|
|
|
class MyModelViewSet(ModelViewSet):
|
|
queryset = MyModel.objects.all()
|
|
serializer_class = MyModelSerializer
|
|
```
|
|
|
|
## Routers
|
|
|
|
Routers map URLs to REST API views (endpoints). NetBox does not provide any custom components for this; the [`DefaultRouter`](https://www.django-rest-framework.org/api-guide/routers/#defaultrouter) class provided by DRF should suffice for most use cases.
|
|
|
|
Routers should be exposed in `api/urls.py`. This file **must** define a variable named `urlpatterns`.
|
|
|
|
### Example
|
|
|
|
```python
|
|
# api/urls.py
|
|
from rest_framework import routers
|
|
from .views import MyModelViewSet
|
|
|
|
router = routers.DefaultRouter()
|
|
router.register('my-model', MyModelViewSet)
|
|
urlpatterns = router.urls
|
|
```
|
|
|
|
This will make the plugin's view accessible at `/api/plugins/my-plugin/my-model/`.
|
|
|
|
!!! warning
|
|
The examples provided here are intended to serve as a minimal reference implementation only. This documentation does not address authentication, performance, or myriad other concerns that plugin authors may need to address.
|