Руководство по конфигурации 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 (such as 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.api import APIField
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",
        "full_url": "http://www.example.com/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 для отсутствия ограничения.