Руководство по настройке Wagtail API v2

Включить приложение

Сначала необходимо включить приложение API Wagtail, чтобы Django его увидел. Добавьте wagtail.api.v2 в INSTALLED_APPS в настройках вашего проекта Django:

# settings.py

INSTALLED_APPS = [
    ...

    'wagtail.api.v2',

    ...
]

По желанию, вы также можете добавить rest_framework в INSTALLED_APPS. Это сделает API доступным для просмотра в веб-браузере, но это не обязательно для базового вывода в формате JSON.

Настройка конечных точек

Далее, нужно настроить, какой контент будет экспонироваться в API. Каждый тип контента (например, страницы, изображения и документы) имеет свою конечную точку. Конечные точки объединяются маршрутизатором, который предоставляет конфигурацию URL, в которую вы можете интегрировать остальную часть своего проекта.

Wagtail предоставляет три класса конечных точек, которые вы можете использовать:

• Страницы wagtail.api.v2.views.PagesAPIViewSet
• Изображения wagtail.images.api.v2.views.ImagesAPIViewSet
• Документы wagtail.documents.api.v2.views.DocumentsAPIViewSet

Вы можете расширить любой из этих классов конечных точек, чтобы настроить их функциональность. Кроме того, есть базовый класс конечной точки, который вы можете использовать для добавления различных типов контента в API: wagtail.api.v2.views.BaseAPIViewSet

В этом примере мы создадим API, который включает все три встроенных типа контента в их стандартной конфигурации:

# api.py

from wagtail.api.v2.views import PagesAPIViewSet
from wagtail.api.v2.router import WagtailAPIRouter
from wagtail.images.api.v2.views import ImagesAPIViewSet
from wagtail.documents.api.v2.views import DocumentsAPIViewSet

# Create the router. "wagtailapi" is the URL namespace
api_router = WagtailAPIRouter('wagtailapi')

# Add the three endpoints using the "register_endpoint" method.
# The first parameter is the name of the endpoint (eg. pages, images). This
# is used in the URL of the endpoint
# The second parameter is the endpoint class that handles the requests
api_router.register_endpoint('pages', PagesAPIViewSet)
api_router.register_endpoint('images', ImagesAPIViewSet)
api_router.register_endpoint('documents', DocumentsAPIViewSet)

Далее, зарегистрируйте URL-адреса, чтобы Django мог перенаправлять запросы в API:

# urls.py

from .api import api_router

urlpatterns = [
    ...

    path('api/v2/', api_router.urls),

    ...

    # Ensure that the api_router line appears above the default Wagtail page serving route
    re_path(r'^', include(wagtail_urls)),
]

С этой конфигурацией страницы будут доступны по адресу /api/v2/pages/, изображения по адресу /api/v2/images/, а документы по адресу /api/v2/documents/.

Добавление пользовательских полей страницы

Вероятно, вам нужно будет экспортировать некоторые пользовательские поля через API. Это можно сделать, добавив список полей, которые необходимо экспортировать в атрибут api_fields для каждой модели страницы.

Например:

# blog/models.py

from wagtail.api import APIField

class BlogPageAuthor(Orderable):
    page = models.ForeignKey('blog.BlogPage', on_delete=models.CASCADE, related_name='authors')
    name = models.CharField(max_length=255)

    api_fields = [
        APIField('name'),
    ]


class BlogPage(Page):
    published_date = models.DateTimeField()
    body = RichTextField()
    feed_image = models.ForeignKey('wagtailimages.Image', on_delete=models.SET_NULL, null=True, ...)
    private_field = models.CharField(max_length=255)

    # Export fields over the API
    api_fields = [
        APIField('published_date'),
        APIField('body'),
        APIField('feed_image'),
        APIField('authors'),  # This will nest the relevant BlogPageAuthor objects in the API response
    ]

Это сделает published_date, body, feed_image и список authors с полем name доступными в API. Но для доступа к этим полям необходимо выбрать тип blog.BlogPage с помощью параметра ?type в самом API.

Пользовательские сериализаторы

Сериализаторы используются для преобразования представления модели в базе данных в формат JSON. Вы можете переопределить сериализатор для любого поля, используя ключевое слово serializer:

from rest_framework.fields import DateField

class BlogPage(Page):
    ...

    api_fields = [
        # Change the format of the published_date field to "Thursday 06 April 2017"
        APIField('published_date', serializer=DateField(format='%A %d %B %Y')),
        ...
    ]

Сериализаторы Django REST Framework могут принимать аргумент source, позволяющий добавлять поля API, у которых другое имя поля или вообще нет базового поля:

from rest_framework.fields import DateField

class BlogPage(Page):
    ...

    api_fields = [
        # Date in ISO8601 format (the default)
        APIField('published_date'),

        # A separate published_date_display field with a different format
        APIField('published_date_display', serializer=DateField(format='%A %d %B %Y', source='published_date')),
        ...
    ]

Это добавит два поля в API (другие поля опущены для краткости):

{
    "published_date": "2017-04-06",
    "published_date_display": "Thursday 06 April 2017"
}

Изображения в API

Сериализатор ImageRenditionField позволяет добавлять варианты изображений в ваш API. Он требует строку фильтра изображений, определяющую операции изменения размера, которые нужно выполнить над изображением. Он также может принимать ключевое слово source , описанное выше.

Например:

from wagtail.images.api.fields import ImageRenditionField

class BlogPage(Page):
    ...

    api_fields = [
        # Adds information about the source image (eg, title) into the API
        APIField('feed_image'),

        # Adds a URL to a rendered thumbnail of the image to the API
        APIField('feed_image_thumbnail', serializer=ImageRenditionField('fill-100x100', source='feed_image')),
        ...
    ]

Это добавит следующее в JSON:

{
    "feed_image": {
        "id": 45529,
        "meta": {
            "type": "wagtailimages.Image",
            "detail_url": "http://www.example.com/api/v2/images/12/",
            "download_url": "/media/images/a_test_image.jpg",
            "tags": []
        },
        "title": "A test image",
        "width": 2000,
        "height": 1125
    },
    "feed_image_thumbnail": {
        "url": "/media/images/a_test_image.fill-100x100.jpg",
        "width": 100,
        "height": 100,
        "alt": "image alt text"
    }
}

Примечание: download_url — это исходный путь загруженного файла, а feed_image_thumbnail['url'] — URL отрендеренного изображения. При использовании другого хранилища, например S3, download_url вернёт URL изображения, если ваши медиафайлы правильно настроены.

WAGTAILAPI_BASE_URL

(требуется при использовании кеширования фронтального отображения)

Это используется в двух местах: при генерации абсолютных URL-адресов файлов документов и при обновлении кэша.

Генерация URL-адресов документов будет использовать текущий хост запроса в качестве резервного варианта, если этот параметр не задан. Однако кеширование не может сделать этого, поэтому этот параметр необходимо установить, когда этот модуль используется вместе с модулем wagtailfrontendcache.

WAGTAILAPI_SEARCH_ENABLED

(по умолчанию: True)

Установка этого параметра в значение false отключит полнотекстовый поиск. Это относится ко всем конечным точкам.

WAGTAILAPI_LIMIT_MAX

(по умолчанию: 20)

Это позволяет изменить максимальное количество результатов, которое пользователь может запросить за один раз. Это относится ко всем конечным точкам. Установите в None для отсутствия ограничения.