Versioning schemes determine how the API version is extracted from incoming requests.
BaseVersioning
Base class for all versioning schemes.
from rest_framework.versioning import BaseVersioning
Attributes
The version to use when no versioning information is present
Set of allowed versions. If set, only these versions will be accepted
The parameter name to use for versioning. Default is 'version'
Methods
determine_version(request, *args, **kwargs)
Determine the API version from the request. Must be implemented by subclasses.
Returns the version string or None.
Return a URL for the given view name, taking versioning into account.
is_allowed_version(version)
Return True if the version is in the allowed set.
Versioning based on the Accept header with a media type parameter.
from rest_framework.versioning import AcceptHeaderVersioning
class MyView(APIView):
versioning_class = AcceptHeaderVersioning
Request Example
GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0
Attributes
Error message for invalid versions. Default is 'Invalid version in "Accept" header.'
URLPathVersioning
Versioning based on URL path keyword arguments.
from rest_framework.versioning import URLPathVersioning
class MyView(APIView):
versioning_class = URLPathVersioning
URL Configuration
from django.urls import path, re_path
urlpatterns = [
re_path(r'^(?P<version>[v1|v2]+)/users/$', users_list, name='users-list'),
re_path(r'^(?P<version>[v1|v2]+)/users/(?P<pk>[0-9]+)/$', users_detail, name='users-detail'),
]
Request Example
GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json
Attributes
Error message for invalid versions. Default is 'Invalid version in URL path.'
Methods
Automatically includes the version in generated URLs.
NamespaceVersioning
Versioning based on Django URL namespaces.
from rest_framework.versioning import NamespaceVersioning
class MyView(APIView):
versioning_class = NamespaceVersioning
URL Configuration
from django.urls import path, include
# users/urls.py
urlpatterns = [
path('users/', users_list, name='users-list'),
path('users/<int:pk>/', users_detail, name='users-detail'),
]
# urls.py
urlpatterns = [
path('v1/', include('users.urls', namespace='v1')),
path('v2/', include('users.urls', namespace='v2')),
]
Request Example
GET /v1/users/ HTTP/1.1
Host: example.com
Accept: application/json
Attributes
Error message for invalid versions. Default is 'Invalid version in URL path. Does not match any version namespace.'
Methods
get_versioned_viewname(viewname, request)
Return the versioned view name by prepending the namespace.
HostNameVersioning
Versioning based on the hostname.
from rest_framework.versioning import HostNameVersioning
class MyView(APIView):
versioning_class = HostNameVersioning
Request Example
GET /bookings/ HTTP/1.1
Host: v1.example.com
Accept: application/json
Attributes
Regex pattern to extract version from hostname. Default matches v1.example.com format
Error message for invalid versions. Default is 'Invalid version in hostname.'
QueryParameterVersioning
Versioning based on a query parameter.
from rest_framework.versioning import QueryParameterVersioning
class MyView(APIView):
versioning_class = QueryParameterVersioning
Request Example
GET /bookings/?version=1.0 HTTP/1.1
Host: example.com
Accept: application/json
Attributes
Error message for invalid versions. Default is 'Invalid version in query parameter.'
Methods
Automatically includes the version as a query parameter in generated URLs.
Example Usage
Global Configuration
# settings.py
REST_FRAMEWORK = {
'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning',
'DEFAULT_VERSION': 'v1',
'ALLOWED_VERSIONS': ['v1', 'v2'],
'VERSION_PARAM': 'version',
}
Per-View Configuration
from rest_framework.versioning import QueryParameterVersioning
from rest_framework.views import APIView
class CustomVersioning(QueryParameterVersioning):
default_version = 'v1'
allowed_versions = ['v1', 'v2', 'v3']
version_param = 'api-version'
class MyView(APIView):
versioning_class = CustomVersioning
def get(self, request):
if request.version == 'v1':
return Response({'message': 'Version 1'})
return Response({'message': 'Version 2+'})
Using Versions in Serializers
class MyViewSet(viewsets.ModelViewSet):
queryset = MyModel.objects.all()
def get_serializer_class(self):
if self.request.version == 'v1':
return MySerializerV1
return MySerializerV2
