Версионирование с помощью фреймворка REST¶

Если версионность API включена, атрибут request.version будет содержать строку, соответствующую версии, запрошенной во входящем клиентском запросе.

По умолчанию версионность не включена, и request.version всегда будет возвращать None.

def get_serializer_class(self):
    if self.request.version == 'v1':
        return AccountSerializerVersion1
    return AccountSerializer

from rest_framework.reverse import reverse

reverse('bookings-list', request=request)

def get(self, request):
    queryset = Booking.objects.all()
    serializer = BookingsSerializer(queryset, many=True, context={'request': request})
    return Response({'all_bookings': serializer.data})

Настройка схемы версионирования¶

Схема версионности определяется ключом настроек DEFAULT_VERSIONING_CLASS.

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning'
}

Если он не задан явно, значением для DEFAULT_VERSIONING_CLASS будет None. В этом случае атрибут request.version всегда будет возвращать None.

Вы также можете установить схему версионирования для отдельного представления. Обычно вам не нужно этого делать, поскольку логичнее иметь единую схему версионирования, используемую глобально. Если это необходимо, используйте атрибут versioning_class.

class ProfileList(APIView):
    versioning_class = versioning.QueryParameterVersioning

from rest_framework.versioning import URLPathVersioning
from rest_framework.views import APIView

class ExampleVersioning(URLPathVersioning):
    default_version = ...
    allowed_versions = ...
    version_param = ...

class ExampleView(APIVIew):
    versioning_class = ExampleVersioning

 AcceptHeaderVersioning¶

Эта схема требует от клиента указать версию как часть типа медиа в заголовке Accept. Версия включается в качестве параметра медиатипа, дополняющего основной медиатип.

Вот пример HTTP-запроса с использованием стиля версионирования заголовка accept.

GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0

В приведенном выше примере запроса атрибут request.version вернет строку '1.0'.

Версионирование на основе заголовков accept является generally considered как :doc:`best practice <https://github.com/interagent/http-api-design/blob/master/en/foundations/require-versioning-in-the-accepts-header>`** , хотя другие стили могут быть подходящими в зависимости от требований клиента.

class BookingsAPIRenderer(JSONRenderer):
    media_type = 'application/vnd.megacorp.bookings+json'

GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/vnd.megacorp.bookings+json; version=1.0

URLPathVersioning¶

Эта схема требует, чтобы клиент указывал версию как часть пути URL.

GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json

Ваш URL conf должен включать шаблон, соответствующий версии с ключевым аргументом 'version', чтобы эта информация была доступна схеме версионирования.

urlpatterns = [
    re_path(
        r'^(?P<version>(v1|v2))/bookings/$',
        bookings_list,
        name='bookings-list'
    ),
    re_path(
        r'^(?P<version>(v1|v2))/bookings/(?P<pk>[0-9]+)/$',
        bookings_detail,
        name='bookings-detail'
    )
]

NamespaceVersioning¶

Для клиента эта схема такая же, как URLPathVersioning. Единственное различие заключается в том, как она настраивается в вашем Django-приложении, поскольку она использует интервалы между именами URL, вместо аргументов ключевых слов URL.

GET /v1/something/ HTTP/1.1
Host: example.com
Accept: application/json

При такой схеме атрибут request.version определяется на основе namespace, который соответствует пути входящего запроса.

В следующем примере мы даем набору представлений два различных возможных префикса URL, каждый из которых относится к разным пространствам имен:

# bookings/urls.py
urlpatterns = [
    re_path(r'^$', bookings_list, name='bookings-list'),
    re_path(r'^(?P<pk>[0-9]+)/$', bookings_detail, name='bookings-detail')
]

# urls.py
urlpatterns = [
    re_path(r'^v1/bookings/', include('bookings.urls', namespace='v1')),
    re_path(r'^v2/bookings/', include('bookings.urls', namespace='v2'))
]

И URLPathVersioning, и NamespaceVersioning разумны, если вам нужна простая схема версионирования. Подход URLPathVersioning может быть более подходящим для небольших специальных проектов, а подход NamespaceVersioning, вероятно, проще в управлении для больших проектов.

HostNameVersioning¶

Схема версионности имени хоста требует от клиента указать запрашиваемую версию как часть имени хоста в URL.

Например, ниже приведен HTTP-запрос к URL http://v1.example.com/bookings/:

GET /bookings/ HTTP/1.1
Host: v1.example.com
Accept: application/json

По умолчанию эта реализация ожидает, что имя хоста будет соответствовать этому простому регулярному выражению:

^([a-zA-Z0-9]+)**.[a-zA-Z0-9]+**.[a-zA-Z0-9]+$

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

Схема HostNameVersioning может быть неудобна для использования в режиме отладки, поскольку обычно вы получаете доступ к необработанному IP-адресу, например 127.0.0.1. Существуют различные онлайн-уроки по работе со схемой access localhost with a custom subdomain, которые могут оказаться полезными в этом случае.

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

QueryParameterVersioning¶

Эта схема представляет собой простой стиль, который включает версию в качестве параметра запроса в URL. Например:

GET /something/?version=0.1 HTTP/1.1
Host: example.com
Accept: application/json

Пример¶

В следующем примере используется пользовательский заголовок X-API-Version для определения запрашиваемой версии.

class XAPIVersionScheme(versioning.BaseVersioning):
    def determine_version(self, request, *args, **kwargs):
        return request.META.get('HTTP_X_API_VERSION', None)

Если ваша схема версионирования основана на URL запроса, вы также захотите изменить способ определения версионированных URL. Для этого вам следует переопределить метод .reverse() в классе. Примеры см. в исходном коде.