Руководство по использованию Wagtail API v2

Модуль Wagtail API предоставляет общедоступный, только для чтения, API в формате JSON, который может использоваться внешними клиентами (например, мобильным приложением) или передней частью сайта.

Этот документ предназначен для разработчиков, использующих API, предоставляемый Wagtail. Для получения информации о том, как включить модуль API на вашем сайте Wagtail, см. Руководство по настройке Wagtail API v2

Получение контента
Поля стандартных конечных точек
Изменения с версии v1

Получение контента

Для получения контента через API выполните GET запрос к одному из следующих конечных пунктов:

Страницы /api/v2/pages/
Изображения /api/v2/images/
Документы /api/v2/documents/

Примечание

Доступные конечные точки и их URL могут различаться в зависимости от того, как был настроен API.

Пример ответа

Каждый ответ содержит список элементов (items) и общее количество (meta.total_count). Общее количество не зависит от пагинации.

GET /api/v2/endpoint_name/

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": "total number of results"
    },
    "items": [
        {
            "id": 1,
            "meta": {
                "type": "app_name.ModelName",
                "detail_url": "http://api.example.com/api/v2/endpoint_name/1/"
            },
            "field": "value"
        },
        {
            "id": 2,
            "meta": {
                "type": "app_name.ModelName",
                "detail_url": "http://api.example.com/api/v2/endpoint_name/2/"
            },
            "field": "different value"
        }
    ]
}

Пользовательские поля страниц в API

На сайтах Wagtail содержится много типов страниц, каждый со своим набором полей. Конечная точка pages по умолчанию будет отображать только общие поля (например, title и slug).

Для доступа к пользовательским полям страниц с помощью API выберите тип страницы с помощью параметра ?type. Это отфильтрует результаты, чтобы отобразить только страницы этого типа, а также сделает все экспортированные пользовательские поля этого типа доступными в API.

Например, для доступа к полям published_date, body и authors модели blog.BlogPage в документации по настройке:

GET /api/v2/pages/?type=blog.BlogPage&fields=published_date,body,authors(name)

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 10
    },
    "items": [
        {
            "id": 1,
            "meta": {
                "type": "blog.BlogPage",
                "detail_url": "http://api.example.com/api/v2/pages/1/",
                "html_url": "http://www.example.com/blog/my-blog-post/",
                "slug": "my-blog-post",
                "first_published_at": "2016-08-30T16:52:00Z"
            },
            "title": "Test blog post",
            "published_date": "2016-08-30",
            "authors": [
                {
                    "id": 1,
                    "meta": {
                        "type": "blog.BlogPageAuthor",
                    },
                    "name": "Karl Hobley"
                }
            ]
        },

        ...
    ]
}

Примечание

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

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

Пагинация

Количество элементов в ответе можно изменить, используя параметр ?limit (по умолчанию: 20), а количество пропускаемых элементов — используя параметр ?offset.

Например:

GET /api/v2/pages/?offset=20&limit=20

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        pages 20 - 40 will be listed here.
    ]
}

Примечание

Может быть максимальное значение для параметра ?limit. Его можно изменить в настройках вашего проекта, установив WAGTAILAPI_LIMIT_MAX либо на число (новое максимальное значение), либо на None (что отключает проверку максимального значения).

Сортировка

Результаты можно отсортировать по любому полю, установив параметр ?order на имя поля для сортировки.

GET /api/v2/pages/?order=title

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        pages will be listed here in ascending title order (a-z)
    ]
}

По умолчанию результаты будут отсортированы по возрастанию. Это можно изменить на убывание, добавив знак - перед именем поля.

GET /api/v2/pages/?order=-title

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        pages will be listed here in descending title order (z-a)
    ]
}

Примечание

Сортировка чувствительна к регистру, поэтому строчные буквы всегда следуют за заглавными при сортировке по возрастанию.

Случайная сортировка

Передача random в параметр ?order вернет результаты в случайном порядке. Если кэширования нет, каждый запрос вернет результаты в другом порядке.

GET /api/v2/pages/?order=random

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 50
    },
    "items": [
        pages will be listed here in random order
    ]
}

Примечание

Использовать ?offset при случайной сортировке невозможно, так как согласованная случайная сортировка не может быть гарантирована при нескольких запросах (поэтому запросы на последующие страницы могут возвращать результаты, которые также появлялись на предыдущих страницах).

Фильтрация

Любое поле может быть использовано в фильтре точного соответствия. Используйте имя фильтра в качестве параметра и значение для сравнения.

Например, для поиска страницы со slug «about»:

GET /api/v2/pages/?slug=about

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 1
    },
    "items": [
        {
            "id": 10,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/10/",
                "html_url": "http://www.example.com/about/",
                "slug": "about",
                "first_published_at": "2016-08-30T16:52:00Z"
            },
            "title": "About"
        },
    ]
}

Фильтрация по положению в дереве (только страницы)

Страницы дополнительно могут быть отфильтрованы по их связи с другими страницами в дереве.

Фильтр ?child_of принимает идентификатор страницы и фильтрует список результатов, чтобы содержать только прямых потомков этой страницы.

Например, это может быть полезно для построения основного меню, передавая идентификатор домашней страницы в фильтр:

GET /api/v2/pages/?child_of=2&show_in_menus=true

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 5
    },
    "items": [
        {
            "id": 3,
            "meta": {
                "type": "blog.BlogIndexPage",
                "detail_url": "http://api.example.com/api/v2/pages/3/",
                "html_url": "http://www.example.com/blog/",
                "slug": "blog",
                "first_published_at": "2016-09-21T13:54:00Z"
            },
            "title": "About"
        },
        {
            "id": 10,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/10/",
                "html_url": "http://www.example.com/about/",
                "slug": "about",
                "first_published_at": "2016-08-30T16:52:00Z"
            },
            "title": "About"
        },

        ...
    ]
}

Фильтр ?ancestor_of принимает идентификатор страницы и фильтрует список, чтобы содержать только предков этой страницы (родитель, прародитель и т. д.) до корневой страницы сайта.

Например, в сочетании с фильтром type он может быть использован для нахождения конкретной blog.BlogIndexPage к которой принадлежит blog.BlogPage. Сам по себе он может быть использован для построения навигационной цепочки от текущей страницы к корневой странице сайта.

Фильтр ?descendant_of принимает идентификатор страницы и фильтрует список, чтобы содержать только потомков этой страницы (дети, внуки и т. д.).

Поиск

Передача запроса в параметр ?search выполнит полнотекстовый поиск по результатам.

Запрос разбивается на «термы» (по границам слов), а затем каждый терм нормализуется (приводится к нижнему регистру и без диакритики).

Например: ?search=James+Joyce

Оператор поиска

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

and - Все термы в поисковом запросе (исключая стоп-слова) должны присутствовать в каждом результате
or - По крайней мере, один терм в поисковом запросе должен присутствовать в каждом результате

Оператор or обычно лучше, чем and, так как он позволяет пользователю быть неточным в запросе, а алгоритм ранжирования будет гарантировать, что нерелевантные результаты не окажутся в верхней части страницы.

Оператор по умолчанию зависит от того, поддерживает ли используемый сайтом поисковый движок ранжирование. Если поддерживает (Elasticsearch), оператор по умолчанию будет or. В противном случае (база данных), по умолчанию будет and.

По той же причине, рекомендуется использовать оператор and при использовании ?search в сочетании с ?order (так как это отключает ранжирование).

Например: ?search=James+Joyce&order=-first_published_at&search_operator=and

Специальные фильтры для интернационализированных сайтов

Когда WAGTAIL_I18N_ENABLED установлено в True (см. Включение интернационализации для получения более подробной информации), на конечной точке страниц становятся доступны два новых фильтра.

Фильтрация страниц по локали

Фильтр ?locale= используется для фильтрации списка, чтобы отобразить только страницы в указанной локали. Например:

GET /api/v2/pages/?locale=en-us

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 5
    },
    "items": [
        {
            "id": 10,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/10/",
                "html_url": "http://www.example.com/usa-page/",
                "slug": "usa-page",
                "first_published_at": "2016-08-30T16:52:00Z",
                "locale": "en-us"
            },
            "title": "American page"
        },

        ...
    ]
}

Получение переводов страницы

Фильтр ?translation_of используется для фильтрации списка, чтобы отобразить только страницы, являющиеся переводом указанной страницы с идентификатором. Например:

GET /api/v2/pages/?translation_of=10

HTTP 200 OK
Content-Type: application/json

{
    "meta": {
        "total_count": 2
    },
    "items": [
        {
            "id": 11,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/11/",
                "html_url": "http://www.example.com/gb-page/",
                "slug": "gb-page",
                "first_published_at": "2016-08-30T16:52:00Z",
                "locale": "en-gb"
            },
            "title": "British page"
        },
        {
            "id": 12,
            "meta": {
                "type": "standard.StandardPage",
                "detail_url": "http://api.example.com/api/v2/pages/12/",
                "html_url": "http://www.example.com/fr-page/",
                "slug": "fr-page",
                "first_published_at": "2016-08-30T16:52:00Z",
                "locale": "fr"
            },
            "title": "French page"
        },
    ]
}

Поля

По умолчанию в ответ возвращается только подмножество доступных полей. Параметр ?fields можно использовать для добавления дополнительных полей в ответ и удаления стандартных полей, которые вам не нужны.

Дополнительные поля

Дополнительные поля могут быть добавлены в ответ, установив ?fields в список имён полей, разделённых запятыми, которые вы хотите добавить.

Например, ?fields=body,feed_image добавит поля body и feed_image в ответ.

Это также можно использовать для отношений. Например, ?fields=body,feed_image(width,height) встроит поля width и height изображения в ответ.

Все поля

Установление ?fields в звездочку (*) добавит все доступные поля в ответ. Это полезно для выяснения, какие поля были экспортированы.

Например: ?fields=*

Удаление полей

Поля, которые вам не нужны, можно удалить, добавив префикс - к имени и включив его в ?fields.

Например, ?fields=-title,body удалит title и добавит body.

Это также можно использовать со звездочкой. Например, ?fields=*,-body добавит все поля, кроме body.

Удаление всех стандартных полей

Чтобы указать точно необходимые поля, можно установить первое поле в списке как нижнее подчеркивание (_), что удалит все стандартные поля.

Например, ?fields=_,title вернёт только поле заголовка.

Просмотры деталей

Вы можете получить один объект из API, добавив его идентификатор в конец URL. Например:

Страницы /api/v2/pages/1/
Изображения /api/v2/images/1/
Документы /api/v2/documents/1/

Все экспортированные поля будут возвращены в ответе по умолчанию. Вы можете использовать параметр ?fields для настройки отображаемых полей.

Например: /api/v2/pages/1/?fields=_,title,body вернёт только поля title и body страницы с идентификатором 1.

Поиск страниц по пути HTML

Вы можете найти отдельную страницу по её пути HTML, используя просмотр /api/v2/pages/find/?html_path=<path>.

Это вернёт либо ответ-перенаправление 302 на страницу со списком деталей, либо ответ 404 «не найдено».

Например: /api/v2/pages/find/?html_path=/ всегда перенаправляет на главную страницу сайта

Поля стандартных конечных точек

Общие поля

Эти поля возвращаются каждой конечной точкой.

Страницы

Изображения

Документы

Изменения с версии v1

Критические изменения

Список результатов в ответах со списком был переименован в items (ранее он был либо pages, images или documents).

Основные возможности

Параметр fields был улучшен для возможности удаления полей, добавления всех полей и настройки вложенных полей.

Дополнительные возможности

Поля html_url, slug, first_published_at, expires_at и show_in_menus были добавлены в конечную точку страниц.
Поле download_url было добавлено в конечную точку документов.
Несколько типов страниц могут быть указаны в параметре type в конечной точке страниц.
true и false теперь могут использоваться при фильтрации полей булевого типа.
order теперь может использоваться в сочетании с search
Параметр search_operator был добавлен.