REST API

Dynamic preferences provides an optional integration with Django REST Framework:

  • Serializers you can use for global and user preferences (or to extend for your own preferences)

  • Viewsets you can use for global and user preferences (or to extend for your own preferences)

Getting started

The easiest way to offer API endpoints to manage preferences in your project is to use bundled viewsets in your urls.py:

from django.urls import include, re_path
from rest_framework import routers

from dynamic_preferences.api.viewsets import GlobalPreferencesViewSet
from dynamic_preferences.users.viewsets import UserPreferencesViewSet


router = routers.SimpleRouter()
router.register(r'global', GlobalPreferencesViewSet, 'global')

# Uncomment this one if you use user preferences
# router.register(r'user', UserPreferencesViewSet, 'user')

api_patterns = [
    re_path(r'^preferences/', include(router.urls, namespace='preferences'))

]
urlpatterns = [
    # your other urls here
    re_path(r'^api/', include(api_patterns, namespace='api'))
]

Endpoints

For each preference viewset, the following endpoints are available:

Example reverse and urls are given according to the previous snippet. You’ll have to adapt them to your own URL namespaces and structure.

List

  • Methods: GET

  • Returns a list of preferences

  • Reverse example: reverse('api:preferences:global-list')

  • URL examples:

    • List all preferences

      /api/preferences/global/

    • List all preferences under blog section

      /api/preferences/global/?section=blog

Detail

  • Methods: GET, PATCH

  • Get or update a single preference

  • Reverse example: reverse('api:preferences:global-detail', kwargs={'pk': 'section__name'})

  • URL example: /api/preferences/global/section__name

If you call this endpoint via PATCH HTTP method, you can update the preference value. The following payload is expected:

{
    value: 'new_value'
}

Note

When updating the preference value, the underlying serializers will call the preference field validators, and the preference validate method, if any is available.

Bulk

  • Methods: POST

  • Update multiple preferences at once

  • Reverse example: reverse('api:preferences:global-bulk')

  • URL example: /api/preferences/global/bulk

If you call this endpoint via POST HTTP method, you can update the the value of multiple preferences at once. Example payload:

{
    section1__name1: 'new_value',
    section2__name2: false,
}

This will update the preferences whose identifiers match section1__name1 and section2__name2 with the corresponding values.

Note

Validation will be called for each preferences, ans save will only occur if no error happens.

A note about permissions

  • GlobalPreferencesViewSet will check the user has the dynamic_preferences.change_globalpreferencemodel permission

  • UserPreferencesViewSet will check the user is logged in and only allow him to edit his own preferences.