REST-фреймворк Django 3.1

Релиз 3.1 является промежуточным этапом в релизах проекта Kickstarter и включает ряд новых функциональных возможностей.

Некоторые основные моменты включают:

  • Суперумная схема пагинации курсора.

  • Улучшенный API пагинации, поддерживающий стили пагинации в заголовке или в тексте.

  • Пагинация управляет рендерингом в просматриваемом API.

  • Улучшенная поддержка версионности API.

  • Встроенная поддержка интернационализации.

  • Поддержка HStoreField и ArrayField в Django 1.8.

Версионирование

Мы сделали его easier to build versioned APIs. Встроенные схемы для версионирования включают как варианты на основе URL, так и варианты на основе заголовка Accept.

При использовании схемы, основанной на URL, сериализаторы с гиперссылками будут разрешать отношения к той же версии API, которая используется во входящем запросе.

Например, при использовании NamespaceVersioning , и следующего сериализатора с гиперссылкой:

class AccountsSerializer(serializer.HyperlinkedModelSerializer):
    class Meta:
        model = Accounts
        fields = ['account_name', 'users']

Выходное представление будет соответствовать версии, использованной во входящем запросе. Например:

GET http://example.org/v2/accounts/10  # Version 'v2'

{
    "account_name": "europa",
    "users": [
        "http://example.org/v2/users/12",  # Version 'v2'
        "http://example.org/v2/users/54",
        "http://example.org/v2/users/87"
    ]
}

Интернационализация

REST framework теперь включает встроенный набор переводов и supports internationalized error responses. Это позволяет вам либо изменить язык по умолчанию, либо позволить клиентам указывать язык через заголовок Accept-Language.

Вы можете изменить язык по умолчанию с помощью стандартной настройки Django LANGUAGE_CODE:

LANGUAGE_CODE = "es-es"

Вы можете включить запрос языка на каждый запрос, добавив LocalMiddleware к настройке MIDDLEWARE_CLASSES:

MIDDLEWARE_CLASSES = [
    ...
    'django.middleware.locale.LocaleMiddleware'
]

Когда интернационализация по каждому запросу включена, клиентские запросы будут соблюдать заголовок Accept-Language, где это возможно. Например, давайте сделаем запрос на неподдерживаемый тип медиа:

Запрос

GET /api/users HTTP/1.1
Accept: application/xml
Accept-Language: es-es
Host: example.org

Ответ

HTTP/1.0 406 NOT ACCEPTABLE

{
    "detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."
}

Обратите внимание, что структура ответов на ошибки остается прежней. У нас по-прежнему есть ключ detail в ответе. При необходимости вы можете изменить и это поведение, используя custom exception handler.

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

Полный список поддерживаемых языков можно найти на нашем сайте Transifex project page.

Если вы хотите поддерживать только подмножество поддерживаемых языков, используйте стандартную настройку Django LANGUAGES:

LANGUAGES = [
    ('de', _('German')),
    ('en', _('English')),
]

Более подробную информацию см. в разделе internationalization documentation.

Большое спасибо Craig Blaszczyk за помощь в продвижении этого проекта.

Новые типы полей

Новые ArrayField, HStoreField и UUIDField в Django 1.8 теперь полностью поддерживаются.

Эта работа также означает, что теперь у нас есть и serializers.DictField() , и serializers.ListField() типы, что позволяет выражать и проверять более широкий набор представлений.

Если вы создаете новый проект 1.8, то вам, вероятно, следует рассмотреть возможность использования UUIDField в качестве первичных ключей для всех ваших моделей. Этот стиль будет автоматически работать с сериализаторами гиперссылок, возвращая URL в следующем стиле:

http://example.org/api/purchases/9b1a433f-e90d-4948-848b-300fdc26365d

API ModelSerializer

Перепроектирование сериализатора в версии 3.0 не включало публичного API для изменения того, как классы ModelSerializer автоматически генерируют набор полей из заданного класса режима. Теперь мы снова ввели API для этого, позволяющий создавать новые базовые классы ModelSerializer, которые ведут себя по-другому, например, используют другой стиль по умолчанию для отношений.

Для получения дополнительной информации см. документацию customizing field mappings для классов ModelSerializer.

Перемещение пакетов из ядра

Мы перенесли ряд пакетов из ядра фреймворка REST в отдельные устанавливаемые пакеты. Если вы сейчас используете эти пакеты, вам не нужно беспокоиться, вам просто нужно pip install новые пакеты и изменить все пути импорта.

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

Это изменение также означает, что мы можем более гибко подходить к выбору внешних пакетов, которые мы рекомендуем. Например, отлично поддерживаемый Django OAuth toolkit теперь продвигается как рекомендуемый нами вариант для интеграции поддержки OAuth.

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

  • OAuth - djangorestframework-oauth

  • XML - djangorestframework-xml

  • YAML - djangorestframework-yaml

  • JSONP - djangorestframework-jsonp

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

pip install djangorestframework-xml

И измените настройки, например, так:

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
        'rest_framework_xml.renderers.XMLRenderer'
    ]
}

Спасибо последнему члену нашей команды технического обслуживания, :doc:`José Padilla <https://github.com/jpadilla/>`** , за выполнение этой работы и принятие на себя ответственности за эти пакеты.

Амортизация

Атрибуты request.DATA , request.FILES и request.QUERY_PARAMS перешли из категории ожидающих устаревания в категорию устаревших. Вместо них используйте request.data и request.query_params, как описано в примечаниях к версии 3.0.

Мета-опции ModelSerializer для write_only_fields , view_name и lookup_field также переведены из разряда ожидающих устаревания в разряд устаревших. Вместо них используйте extra_kwargs, как описано в примечаниях к версии 3.0.

Все эти атрибуты и опции будут по-прежнему работать в версии 3.1, но их использование будет вызывать предупреждение. Они будут полностью удалены в версии 3.2.

Что дальше?

Следующее внимание будет уделено HTML-рендерингу результатов API и будет включать в себя:

  • Рендеринг HTML-формы сериализаторов.

  • Элементы управления фильтрацией, встроенные в просматриваемый API.

  • Альтернативный интерфейс в стиле администратора.

Это будет сделано либо в виде единого релиза 3.2, либо разделено на два отдельных релиза, при этом HTML-формы и элементы управления фильтрами появятся в 3.2, а интерфейс в стиле администратора - в релизе 3.3.

Вернуться на верх