Руководство по конфигурации Wagtail API v2

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

Несмотря на то, что API построен на Django REST Framework, вам не нужно устанавливать его вручную, так как он уже является зависимостью Wagtail.

Основная конфигурация

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

В первую очередь, вам нужно включить приложение 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 могут принимать аргумент источник, что позволяет добавлять поля 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-адресов документов будет использовать хост текущего запроса в качестве fallback, если этот параметр не задан. Однако кеширование не может этого сделать, поэтому этот параметр необходимо задать при использовании этого модуля вместе с модулем wagtailfrontendcache.

WAGTAILAPI_SEARCH_ENABLED

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

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

WAGTAILAPI_LIMIT_MAX

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

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