Руководство по использованию 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
    ]
}

Фильтрация

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

Например, чтобы найти страницу со слагом «о нас»:

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

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

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

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

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

Поиск

Передача запроса в параметр ?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, добавив его ID в конец URL. Например:

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

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

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

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

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

Это вернёт либо ответ с перенаправлением 302 на страницу с детальным представлением, либо ответ 404 об отсутствии страницы.

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

Общие поля

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

Страницы

Изображения

Документы

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

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