Django Web Framework Tutorials

Versioning APIs in Django Rest Framework Guide with Examples

Last Updated: by

Versioning APIs is a crucial practice in web development that allows you to make changes to your API while ensuring backward compatibility for existing clients. In this tutorial, we’ll explore how to implement API versioning in Django Rest Framework (DRF) using different strategies along with practical examples.

Why Version APIs?

As your application evolves, you might need to introduce changes to your API endpoints, request/response structures, or data representations. However, existing clients might depend on the current API structure. Versioning helps maintain a balance between introducing new features and supporting existing clients.

1. URL Path Versioning

URL path versioning involves including the version number in the URL itself. It’s straightforward and easy to understand.

Example:

# urls.py
from django.urls import path, include
from rest_framework.urlpatterns import format_suffix_patterns
from . import views

urlpatterns = [
    path('v1/', include('myapp.v1_urls')),  # Include v1 URLs
    path('v2/', include('myapp.v2_urls')),  # Include v2 URLs
]

# myapp/v1_urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('items/', views.ItemListView.as_view(), name='item-list'),
    # ... v1 endpoints
]

# myapp/v2_urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('items/', views.NewItemListView.as_view(), name='new-item-list'),
    # ... v2 endpoints
]

2. Accept Header Versioning

Accept header versioning relies on the Accept header in the HTTP request to specify the desired version.

Example:

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.AcceptHeaderVersioning',
    'ALLOWED_VERSIONS': ['1.0', '2.0'],
    'DEFAULT_VERSION': '1.0',
}

# views.py
from rest_framework.views import APIView
from rest_framework.response import Response

class ItemListView(APIView):
    def get(self, request, format=None):
        items = [{'name': 'item1'}, {'name': 'item2'}]
        return Response(items)

3. Query Parameter Versioning

Query parameter versioning involves specifying the version in a query parameter of the request.

Example:

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.QueryParameterVersioning',
    'ALLOWED_VERSIONS': ['1.0', '2.0'],
    'DEFAULT_VERSION': '1.0',
}

# views.py
from rest_framework.views import APIView
from rest_framework.response import Response

class ItemListView(APIView):
    def get(self, request, format=None):
        version = request.version
        items = [{'name': 'item1', 'version': version}, {'name': 'item2', 'version': version}]
        return Response(items)

Conclusion

API versioning is essential for maintaining a stable and reliable interface for your clients as your application evolves. In this tutorial, we covered three common strategies for versioning APIs in Django Rest Framework: URL path versioning, accept header versioning, and query parameter versioning.

By implementing versioning, you can ensure that your API remainns backward compatible, allowing both existing and new clients to interact seamlessly with your application. Choose the versioning strategy that best fits your project’s requirements and start building APIs that cater to various client needs while preserving consistency.

Blogs You Might Like to Read!