API

Lotus has an optional Web API built with Django REST framework (also known as DRF) and implements everything to get contents.

As said before, this is optional and you need to enable it on your own (see below).

It currently have some difference with the HTML frontend:

  • This is a read only API, you won’t be able to use it to add, edit or delete contents;

  • Preview mode is implemented but is tied to User session and there is actually no endpoint to enable it or disable it, you still have to use the front;

  • No images are thumbnailed, all media URLs point to the original uploaded file;

Install

First you need to install Lotus with extra requirement for API:

pip install django-blog-lotus[api]

Then you need to mount it in your urls, add the following line into the urlpatterns = [...] from project urls.py :

path("api/", include("lotus.api_urls")),

Obviously you can use the url path you want instead of api/.

Then enable it in Django enabled applications before Lotus (in any order with Breadcrumbs):

INSTALLED_APPS = (
    ...
    "rest_framework",
    ...
    "lotus",
)

Also you may want to add settings for Django REST framework itself like these ones:

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        # Use Django"s standard `django.contrib.auth` permissions,
        # or allow read-only access for unauthenticated users.
        "rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly",
        # Only Django"s standard `django.contrib.auth` permissions, every
        # authenticated user can read and anonymous are never allowed
        # "rest_framework.permissions.DjangoModelPermissions",
    ],
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.LimitOffsetPagination",
    "PAGE_SIZE": 20
}

Internationalization

Lotus API stands on what is implemented from DRF to determine language.

On default installation, the API is not mounted with django.conf.urls.i18n.i18n_patterns so the only way to switch language is through a cookie or HTTP headers. You could use i18n_patterns to allow language prefix in URL but it is not recommended because clients should not have to change language prefix in each URL to navigate in contents.

Authentication & Permissions

Default Lotus installation let the API usage to be opened to anyone. However from your settings you may close it to authentificated user only :

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        # Only Django"s standard `django.contrib.auth` permissions, every
        # authenticated user can read and anonymous are never allowed
        "rest_framework.permissions.DjangoModelPermissions",
    ],
    ...
}

Lotus on itself does not implement any specific permission.

Data serialization

Lotus try a little bit to optimize request with specific serializer depending of viewsets. This means that object list payload does not include every data from an object, only the necessary fields.

So commonly for each model there are three serializers:

  • The full one which output every fields from an object, it is means to be used for a detail viewset;

  • The resumed one which outputs only necessary fields to list objects, it is means to be used for a list viewset;

  • The minimal one which outputs only a few set of fields, it is means to be used when object is included into another object payload (like for Category into Article list);

API browser

You can replace default API browser with either:

‘drf-redesign’ is the simpliest to install but with more modest improvement compared to ‘drf-spectacular’.