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

Управление версиями API позволяет изменять поведение между разными клиентами. Платформа REST предоставляет ряд различных схем управления версиями.

Управление версиями определяется входящим запросом клиента и может основываться либо на URL-адресе запроса, либо на основе заголовков запроса.

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

Пример приложения с двумя подходами для управления версиями API с помощью django rest framework

Первый подход реализован в alpha приложении django.

При таком подходе API v1 и v2 используют общую модель, но имеют собственные представления и сериализаторы.

Альфа-версия — полностью отдельные представления и сериализаторы для каждой версии API.

Структура приложения

├── api_v1
│   ├── serializers.py
│   ├── urls.py
│   └── views.py
├── api_v2
│   ├── serializers.py
│   ├── urls.py
│   └── views.py
├── apps.py
└── models.py

Второй подход реализован в beta приложении django.

При таком подходе API v1 и v2 используют общую модель и представление, но имеют собственные сериализаторы. SerializerClassMixin Представлен общий вид для обеих версий .

Бета-версия — использование одного и того же набора представлений с разными сериализаторами

Структура приложения

├── api
│   ├── v1
│   │   └── serializers.py
│   ├── v2
│   │   └── serializers.py
│   ├── urls.py
│   └── views.py
├── apps.py
├── mixins.py
└── models.py

В этом случае SerializerClassMixin вводится, поэтому мы можем определить представление следующим образом:

version_map = {
    'v1': BetaSerializer_v1,
    'v2': BetaSerializer_v2,
}

class BetaViewSet(SerializerClassMixin, viewsets.ModelViewSet):
    version_map = version_map
    queryset = Beta.objects.all()

Ключ для version_map должен быть таким же, как у нас в основном urls.py пространстве имен для определенного пути.

Оба подхода можно смешивать даже в одном и том же приложении djanogo.

Составление URL-адресов в основном urls.py

Каждое приложение router показывает, какой из них является drf SimpleRouter.

from rest_framework.routers import SimpleRouter
router = SimpleRouter()
router.register(r'app', AppViewSet)

Основной urls.py создает экземпляр DefaultRouter и расширяет его с помощью маршрутизаторов приложений.

from rest_framework.routers import DefaultRouter
from alpha.api_v1.urls import router as alpha_v1_router
from alpha.api_v2.urls import router as alpha_v2_router
from beta.api.urls imprt router as beta_router

v1_router = DefaultRouter()
v1_router.registry.extend(alpha_v1_router.registry)
v1_router.registry.extend(beta_router)

v2_router = DefaultRouter()
v2_router.registry.extend(alpha_v2_router.registry)
v2_router.registry.extend(beta_router.registry)

urlpatterns = [
    path('api/v1/', include((v1_router.urls, 'api'), namespace='v1')),
    path('api/v2/', include((v2_router.urls, 'api'), namespace='v2')),
]