Bài 10.1: API Versioning & Documentation - Phần 1 - API Versioning

**Series Navigation:** - **Bài 10.1 (bài này): API Versioning** 👈 - [Bài 10.2: OpenAPI & Swagger](./010-api-versioning-documentation-part2.md) - [Bài 10.3: drf-spectacular](./010-api-versioning-documentation-part3.md) - [Bài 10.4: Advanced Documentation](./010-api-versioning-documentation-part4.md)

Mục Tiêu Bài 10.1

Sau khi hoàn thành Bài 10.1 này, bạn sẽ:

✅ Understand why API versioning is important
✅ Implement URL versioning
✅ Implement header versioning
✅ Implement accept header versioning
✅ Use namespace versioning
✅ Handle versioned serializers
✅ Follow versioning best practices

Why API Versioning?

Problem Without Versioning

Scenario:

# Original API (v1){    "id": 1,    "name": "John Doe",    "email": "john@example.com"} # You need to change structure{    "id": 1,    "first_name": "John",  # Changed!    "last_name": "Doe",     # Changed!    "email": "john@example.com"} # Result: Breaks all existing clients! 💥

Solution: API Versioning

# v1 API - Keep for existing clientsGET /api/v1/users/1/{    "id": 1,    "name": "John Doe",    "email": "john@example.com"} # v2 API - New structure for new clientsGET /api/v2/users/1/{    "id": 1,    "first_name": "John",    "last_name": "Doe",    "email": "john@example.com"}

Benefits:

✅ Backward compatibility
✅ Gradual migration
✅ No breaking changes
✅ Multiple versions coexist

Versioning Strategies

1. URL Path Versioning (Recommended)

Format: /api/v1/resource/ or /api/v2/resource/

Pros:

✅ Clear and visible
✅ Easy to test in browser
✅ Easy to cache
✅ RESTful

Cons:

❌ URL changes between versions

2. Query Parameter Versioning

Format: /api/resource/?version=1

Pros:

✅ URL path stays same
✅ Easy to implement

Cons:

❌ Less RESTful
❌ Can be forgotten
❌ Harder to cache

3. Header Versioning

Format: Header X-API-Version: 1

Pros:

✅ URL stays same
✅ Clean URLs

Cons:

❌ Hidden version
❌ Hard to test in browser
❌ Can be forgotten

4. Accept Header Versioning

Format: Header Accept: application/json; version=1.0

Pros:

✅ RESTful (content negotiation)
✅ URL stays same

Cons:

❌ Complex
❌ Hard to test

Comparison

Strategy	Visibility	RESTful	Caching	Ease of Use
URL Path	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Query Param	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
Header	⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐
Accept Header	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐

URL Path Versioning

Basic Setup

# settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',    'DEFAULT_VERSION': 'v1',    'ALLOWED_VERSIONS': ['v1', 'v2'],    'VERSION_PARAM': 'version',}

URL Configuration

# urls.pyfrom django.urls import path, includefrom rest_framework.routers import DefaultRouterfrom myapp.views import ArticleViewSet router = DefaultRouter()router.register('articles', ArticleViewSet, basename='article') urlpatterns = [    path('api/v1/', include(router.urls)),    path('api/v2/', include(router.urls)),]

View Implementation

# views.pyfrom rest_framework import viewsetsfrom myapp.models import Articlefrom myapp.serializers import ArticleV1Serializer, ArticleV2Serializer class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()        def get_serializer_class(self):        """Return different serializer based on version"""        if self.request.version == 'v1':            return ArticleV1Serializer        elif self.request.version == 'v2':            return ArticleV2Serializer        return ArticleV1Serializer # Usage:# GET /api/v1/articles/  → Uses ArticleV1Serializer# GET /api/v2/articles/  → Uses ArticleV2Serializer

Versioned Serializers

# serializers.pyfrom rest_framework import serializersfrom myapp.models import Article # Version 1 - Original structureclass ArticleV1Serializer(serializers.ModelSerializer):    author_name = serializers.CharField(source='author.username', read_only=True)        class Meta:        model = Article        fields = ['id', 'title', 'content', 'author_name', 'created_at'] # Version 2 - New structure with more detailsclass ArticleV2Serializer(serializers.ModelSerializer):    author = serializers.SerializerMethodField()    tags = serializers.StringRelatedField(many=True)        class Meta:        model = Article        fields = [            'id', 'title', 'content', 'author',             'tags', 'views', 'likes', 'created_at', 'updated_at'        ]        def get_author(self, obj):        return {            'id': obj.author.id,            'username': obj.author.username,            'email': obj.author.email        }

Versioned Behavior

class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()        def get_serializer_class(self):        if self.request.version == 'v1':            return ArticleV1Serializer        return ArticleV2Serializer        def get_queryset(self):        """Different querysets for different versions"""        queryset = super().get_queryset()                if self.request.version == 'v1':            # v1: Only published articles            return queryset.filter(status='published')        elif self.request.version == 'v2':            # v2: All articles (with permission check)            return queryset                return queryset        def perform_create(self, serializer):        """Version-specific create logic"""        if self.request.version == 'v1':            # v1: Auto-publish            serializer.save(author=self.request.user, status='published')        elif self.request.version == 'v2':            # v2: Save as draft            serializer.save(author=self.request.user, status='draft')

Header Versioning

Setup

# settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.AcceptHeaderVersioning',    'DEFAULT_VERSION': 'v1',    'ALLOWED_VERSIONS': ['v1', 'v2'],}

Custom Header Versioning

# versioning.pyfrom rest_framework.versioning import BaseVersioning class CustomHeaderVersioning(BaseVersioning):    """    Versioning based on custom header    Header: X-API-Version: 1.0    """        def determine_version(self, request, *args, **kwargs):        version = request.META.get('HTTP_X_API_VERSION')                if not version:            return self.default_version                # Validate version        if version not in self.allowed_versions:            raise exceptions.NotAcceptable(                f'Invalid version: {version}. '                f'Allowed versions: {self.allowed_versions}'            )                return version # settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'myapp.versioning.CustomHeaderVersioning',    'DEFAULT_VERSION': '1.0',    'ALLOWED_VERSIONS': ['1.0', '2.0'],}

Usage

# Request with version headercurl -H "X-API-Version: 1.0" http://localhost:8000/api/articles/ # Without header (uses default)curl http://localhost:8000/api/articles/

Accept Header Versioning

Setup

# settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.AcceptHeaderVersioning',    'DEFAULT_VERSION': 'v1',    'ALLOWED_VERSIONS': ['v1', 'v2'],}

Custom Accept Header

# versioning.pyfrom rest_framework.versioning import AcceptHeaderVersioning class MediaTypeVersioning(AcceptHeaderVersioning):    """    Versioning based on media type    Accept: application/vnd.myapp.v1+json    """        def determine_version(self, request, *args, **kwargs):        media_type = request.accepted_media_type                # Parse version from media type        # e.g., "application/vnd.myapp.v1+json" → "v1"        if 'vnd.myapp' in media_type:            parts = media_type.split('.')            for part in parts:                if part.startswith('v') and part[1:].isdigit():                    version = part                                        if version in self.allowed_versions:                        return version                return self.default_version

Usage

# Request with versioned media typecurl -H "Accept: application/vnd.myapp.v1+json" \     http://localhost:8000/api/articles/ curl -H "Accept: application/vnd.myapp.v2+json" \     http://localhost:8000/api/articles/

Namespace Versioning

Setup

# settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning',    'DEFAULT_VERSION': 'v1',    'ALLOWED_VERSIONS': ['v1', 'v2'],}

URL Configuration

# urls.pyfrom django.urls import path, include urlpatterns = [    path('api/', include(('myapp.urls.v1', 'v1'), namespace='v1')),    path('api/', include(('myapp.urls.v2', 'v2'), namespace='v2')),] # myapp/urls/v1.pyfrom rest_framework.routers import DefaultRouterfrom myapp.views.v1 import ArticleViewSet router = DefaultRouter()router.register('articles', ArticleViewSet, basename='article')urlpatterns = router.urls # myapp/urls/v2.pyfrom rest_framework.routers import DefaultRouterfrom myapp.views.v2 import ArticleViewSet router = DefaultRouter()router.register('articles', ArticleViewSet, basename='article')urlpatterns = router.urls

Separate Views per Version

# myapp/views/v1.pyfrom rest_framework import viewsetsfrom myapp.models import Articlefrom myapp.serializers.v1 import ArticleSerializer class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.filter(status='published')    serializer_class = ArticleSerializer # myapp/views/v2.pyfrom rest_framework import viewsetsfrom myapp.models import Articlefrom myapp.serializers.v2 import ArticleSerializer class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()    serializer_class = ArticleSerializer

Versioning Best Practices

1. Semantic Versioning

# Use semantic versioning: MAJOR.MINOR.PATCH'1.0.0'  # Initial release'1.1.0'  # New features, backward compatible'1.1.1'  # Bug fixes'2.0.0'  # Breaking changes

2. Deprecation Strategy

# views.pyfrom rest_framework.decorators import api_viewfrom rest_framework.response import Responseimport warnings class ArticleViewSet(viewsets.ModelViewSet):    queryset = Article.objects.all()        def get_serializer_class(self):        if self.request.version == 'v1':            # Add deprecation warning            warnings.warn(                'API v1 is deprecated and will be removed in 6 months. '                'Please migrate to v2.',                DeprecationWarning            )        return ArticleV1Serializer if self.request.version == 'v1' else ArticleV2Serializer        def list(self, request, *args, **kwargs):        response = super().list(request, *args, **kwargs)                # Add deprecation header for v1        if request.version == 'v1':            response['X-API-Deprecated'] = 'true'            response['X-API-Sunset'] = '2025-06-30'  # Sunset date            response['Link'] = '</api/v2/articles/>; rel="successor-version"'                return response

3. Version Documentation

class ArticleViewSet(viewsets.ModelViewSet):    """    Article API        Versions:    - v1 (deprecated): Returns only published articles with basic fields    - v2 (current): Returns all articles with full details        v1 will be sunset on 2025-06-30    """    queryset = Article.objects.all()        def get_serializer_class(self):        return ArticleV1Serializer if self.request.version == 'v1' else ArticleV2Serializer

4. Default to Latest Stable

# settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',    'DEFAULT_VERSION': 'v2',  # Latest stable    'ALLOWED_VERSIONS': ['v1', 'v2'],}

5. Limit Supported Versions

# Only support 2-3 versions at a time'ALLOWED_VERSIONS': ['v1', 'v2']  # Support only latest 2 # Sunset old versions# v1 deprecated → v2 current → v3 beta

6. Testing All Versions

# tests/test_versioning.pyfrom rest_framework.test import APITestCase class ArticleVersioningTest(APITestCase):    def test_v1_response_format(self):        """Test v1 returns correct format"""        response = self.client.get('/api/v1/articles/1/')        self.assertEqual(response.status_code, 200)        self.assertIn('author_name', response.data)        self.assertNotIn('author', response.data)        def test_v2_response_format(self):        """Test v2 returns correct format"""        response = self.client.get('/api/v2/articles/1/')        self.assertEqual(response.status_code, 200)        self.assertIn('author', response.data)        self.assertIsInstance(response.data['author'], dict)

Complete Versioning Example

# models.pyfrom django.db import modelsfrom django.contrib.auth.models import User class Article(models.Model):    title = models.CharField(max_length=200)    content = models.TextField()    author = models.ForeignKey(User, on_delete=models.CASCADE)    status = models.CharField(max_length=20, default='draft')    views = models.IntegerField(default=0)    likes = models.IntegerField(default=0)    created_at = models.DateTimeField(auto_now_add=True)    updated_at = models.DateTimeField(auto_now=True) # serializers/v1.pyclass ArticleV1Serializer(serializers.ModelSerializer):    """    v1 API: Simple structure    Deprecated: Use v2    """    author_name = serializers.CharField(source='author.username', read_only=True)        class Meta:        model = Article        fields = ['id', 'title', 'content', 'author_name', 'created_at'] # serializers/v2.pyclass ArticleV2Serializer(serializers.ModelSerializer):    """    v2 API: Enhanced structure    Current version    """    author = serializers.SerializerMethodField()    stats = serializers.SerializerMethodField()        class Meta:        model = Article        fields = [            'id', 'title', 'content', 'author', 'status',            'stats', 'created_at', 'updated_at'        ]        def get_author(self, obj):        return {            'id': obj.author.id,            'username': obj.author.username,            'email': obj.author.email        }        def get_stats(self, obj):        return {            'views': obj.views,            'likes': obj.likes        } # views.pyclass ArticleViewSet(viewsets.ModelViewSet):    """    Article API with versioning        Supported versions:    - v1 (deprecated): Will be sunset on 2025-06-30    - v2 (current): Latest version with enhanced features    """        def get_queryset(self):        queryset = Article.objects.select_related('author')                # Version-specific filtering        if self.request.version == 'v1':            # v1: Only published            return queryset.filter(status='published')        elif self.request.version == 'v2':            # v2: User can see own drafts + published            if self.request.user.is_authenticated:                from django.db.models import Q                return queryset.filter(                    Q(status='published') | Q(author=self.request.user)                )            return queryset.filter(status='published')                return queryset        def get_serializer_class(self):        if self.request.version == 'v1':            return ArticleV1Serializer        return ArticleV2Serializer        def list(self, request, *args, **kwargs):        response = super().list(request, *args, **kwargs)                # Add version info to headers        response['X-API-Version'] = request.version                # Deprecation warning for v1        if request.version == 'v1':            response['X-API-Deprecated'] = 'true'            response['X-API-Sunset'] = '2025-06-30'            response['Warning'] = (                '299 - "API v1 is deprecated. '                'Please migrate to v2 by 2025-06-30"'            )                return response # urls.pyfrom django.urls import path, includefrom rest_framework.routers import DefaultRouter router_v1 = DefaultRouter()router_v1.register('articles', ArticleViewSet, basename='article') router_v2 = DefaultRouter()router_v2.register('articles', ArticleViewSet, basename='article') urlpatterns = [    path('api/v1/', include(router_v1.urls)),    path('api/v2/', include(router_v2.urls)),] # settings.pyREST_FRAMEWORK = {    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',    'DEFAULT_VERSION': 'v2',    'ALLOWED_VERSIONS': ['v1', 'v2'],    'VERSION_PARAM': 'version',}

Usage Examples:

# v1 API (deprecated)GET /api/v1/articles/Response:{    "count": 10,    "results": [        {            "id": 1,            "title": "Article 1",            "content": "...",            "author_name": "john",            "created_at": "2024-01-01T00:00:00Z"        }    ]}Headers:  X-API-Version: v1  X-API-Deprecated: true  X-API-Sunset: 2025-06-30  Warning: 299 - "API v1 is deprecated..." # v2 API (current)GET /api/v2/articles/Response:{    "count": 15,    "results": [        {            "id": 1,            "title": "Article 1",            "content": "...",            "author": {                "id": 5,                "username": "john",                "email": "john@example.com"            },            "status": "published",            "stats": {                "views": 100,                "likes": 10            },            "created_at": "2024-01-01T00:00:00Z",            "updated_at": "2024-01-02T00:00:00Z"        }    ]}Headers:  X-API-Version: v2

Tóm Tắt Bài 10.1

Trong Bài 10.1 này, bạn đã học:

✅ Why Versioning:

Backward compatibility
Gradual migration
No breaking changes

✅ Versioning Strategies:

URL path versioning (recommended)
Query parameter versioning
Header versioning
Accept header versioning

✅ URL Path Versioning:

Configuration
Versioned serializers
Versioned behavior

✅ Other Strategies:

Header versioning
Accept header versioning
Namespace versioning

✅ Best Practices:

Semantic versioning
Deprecation strategy
Version documentation
Default to latest
Limit versions
Testing

Next Steps

Trong Bài 10.2, bạn sẽ học:

OpenAPI specification
Swagger UI
ReDoc
API schema generation
Interactive documentation

Navigation:

Bài 10.1: API Versioning (current)
Bài 10.2: OpenAPI & Swagger →

#backward-compatibility

API Versioning & Documentation - Phần 1 - API Versioning