API Overview

We have implemented a REST API. This uses the Django Rest Framework, see https://www.django-rest-framework.org/

Installation is mostly standard, see https://www.django-rest-framework.org/#installation

Custom Authentication

API authentication is configured in openl2m/settings.py, and would typically look something like this:

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.TokenAuthentication",
        "rest_framework.authentication.SessionAuthentication",  # useful for AJAX calls from web ui clients.
    ]
}

We use a custom Token() class, defined in users/models.py. This adds some extra fields, such as expiration time, permitted client IP, etc. (Note: this is copied from the Netbox code)

The authentication against this token is implemented in the TokenAuthentication() class in openl2m/api/authentication.py

So we have modified the authentication stanza as follows, to use our custom class for token auth:

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "openl2m.api.authentication.TokenAuthentication",  # custom Token(), adopted from Netbox.
        "rest_framework.authentication.SessionAuthentication",  # useful for AJAX calls from web ui clients.
    ]
}

API Root

API urls are defined in openl2m/urls.py, under the api/ path. We define the root, and an endpoint called api/stats/ that returns some statistics about OpenL2M.

Here, we also include API paths to the various apps that implement API extensions.

E.g. the API paths below /api/switches/ come from the file switches/api/urls.py, which maps to specific functions or classes for each api url.

The API root is defined in openl2m/views.py, in class APIRootView(), as is the statistics endpoint in class APIStatsView().

Switches API

Switches app API endpoints are defined in switches/api/urls.py, and the implementations of those are in switches/api/views.py

All API endpoints are documented here.

Code has been refactored, such that both the WEB UI, and the API use the same functions to perform actions. Ie. both switches/views.py and switches/api/views.py now call various perform_xyz() functions implemented in switches/actions.py

This ensures that security, and actions are identical, independent of the path to the action (WEB UI or API).

Users API

Users app API endpoints are defined in users/api/urls.py, and the implementations of those are in users/api/views.py

All API endpoints are documented here.

At time of this writing, the Users API only implemented the ‘get token’ call, at /api/users/token.