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

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

Каждый ответ содержит список элементов (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_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.
    ]
}

Сортировка

Результаты можно отсортировать по любому полю, установив параметр ?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)
    ]
}

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
    ]
}

Фильтрование

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

Например, чтобы найти страницу со слагом «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 принимает идентификатор страницы и фильтрует список, чтобы включать только потомков этой страницы (детей, внуков и т. д.).

Фильтрование страниц по сайту

По умолчанию API будет искать сайт на основе хост-имени запроса. В некоторых случаях вам может потребоваться запросить страницы, принадлежащие другому сайту. Фильтр ?site= используется для фильтрации списка, чтобы включить только страницы, принадлежащие конкретному сайту. Фильтр требует настроенного хост-имени сайта. Если у вас есть несколько сайтов, использующих одно и то же хост-имя, но разные номера портов, можно отфильтровать по номеру порта, используя формат hostname:port. Например:

GET /api/v2/pages/?site=demo-site.local
GET /api/v2/pages/?site=demo-site.local:8080

Поиск

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

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

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

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

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

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"
        },

        ...
    ]
}

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 может быть использован для добавления дополнительных полей в ответ и удаления полей по умолчанию, которые вам не понадобятся.

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

Вы можете получить отдельный объект из 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=/ всегда перенаправляет на главную страницу сайта

Общие поля

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

id (число) Уникальный идентификатор объекта

type (строка) Тип объекта в формате app_label.ModelName

detail_url (строка) URL страницы подробностей для объекта

Страницы

title (строка) meta.slug (строка) meta.show_in_menus (логическое значение) meta.seo_title (строка) meta.search_description (строка) meta.first_published_at (дата/время) Эти значения взяты из соответствующих полей на странице

meta.html_url (строка) Если сайт имеет HTML-фронтенд, сгенерированный Wagtail, это поле будет установлено в URL этой страницы

meta.parent Вложенная информация о родительской странице (доступна только на страницах подробностей)

meta.alias_of (словарь) Если страница помечена как псевдоним, возвращает исходный идентификатор страницы и полный URL

Изображения

title (строка) Значение поля заголовка изображения. В Wagtail это используется в атрибуте HTML alt изображения.

width (число) height (число) Размер исходного файла изображения

meta.tags (список строк) Список тегов, связанных с изображением

Документы

title (строка) Значение поля заголовка документа

meta.tags (список строк) Список тегов, связанных с документом

meta.download_url (строка) URL файла документа

Изменения, требующие переделки

• Список результатов в ответах со списком был переименован в 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 параметр был добавлен