django-api-versioning 0.3.8__tar.gz → 1.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/CHANGELOG.md +56 -1
- django_api_versioning-1.0.1/PKG-INFO +223 -0
- django_api_versioning-1.0.1/README.md +173 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/lifecycle.py +31 -4
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/settings.py +35 -0
- django_api_versioning-1.0.1/django_api_versioning.egg-info/PKG-INFO +223 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning.egg-info/requires.txt +3 -1
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/pyproject.toml +13 -17
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/requirements-dev.txt +3 -2
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_lifecycle.py +56 -14
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_settings.py +26 -0
- django_api_versioning-0.3.8/PKG-INFO +0 -1109
- django_api_versioning-0.3.8/README.md +0 -1061
- django_api_versioning-0.3.8/django_api_versioning.egg-info/PKG-INFO +0 -1109
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/LICENSE +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/MANIFEST.in +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/__init__.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/channels.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/decorators.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/exceptions.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/management/__init__.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/management/commands/__init__.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/management/commands/check_versions.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/management/commands/migrate_endpoints.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/py.typed +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/registry.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/reverse.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/testing.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/urls.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning.egg-info/SOURCES.txt +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning.egg-info/dependency_links.txt +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning.egg-info/top_level.txt +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/pytest.ini +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/requirements.txt +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/setup.cfg +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/__init__.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/conftest.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/settings.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_channels.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_channels_extra.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_decorators.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_distribution_contents.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_exceptions.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_management_commands.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_registry.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_reverse.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_segment_model.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_testing_utils.py +0 -0
- {django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/tests/test_urls.py +0 -0
|
@@ -8,6 +8,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [1.0.1] - 2026-11-17
|
|
12
|
+
|
|
13
|
+
### Documentation
|
|
14
|
+
|
|
15
|
+
- Rework the README onboarding flow to show a working DRF example and generated version routes before the detailed explanation.
|
|
16
|
+
- Add descriptive links to the official documentation site and PyPI, plus the website logo and current PyPI version badge.
|
|
17
|
+
- Use absolute repository links in the README so the PyPI long description retains working source links.
|
|
18
|
+
- Expand and reconcile the canonical API reference, routing contract, article index, and documentation ownership guidance.
|
|
19
|
+
- Correct lifecycle documentation and examples to match the released 1.0.0 behavior.
|
|
20
|
+
- Add and refine Homepage, Documentation, Source, Issues, Changelog, and Security project URLs in package metadata.
|
|
21
|
+
|
|
22
|
+
### Packaging
|
|
23
|
+
|
|
24
|
+
- Publish updated project metadata and documentation only; no runtime code or dependency changes.
|
|
25
|
+
|
|
26
|
+
## [1.0.0] - 2026-11-16
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
- Emit the RFC 9745 date-valued `Deprecation` Structured Field from `API_VERSION_LIFECYCLE[*].deprecated_at`.
|
|
31
|
+
- Add Windows and macOS smoke coverage for Python 3.12 / Django 5.2 alongside the existing 15-environment Linux compatibility matrix.
|
|
32
|
+
|
|
33
|
+
### Changed
|
|
34
|
+
|
|
35
|
+
- Validate lifecycle status values and ISO 8601 lifecycle dates during settings initialization. Deprecated versions require `deprecated_at`; retired versions require `sunset`; supported statuses are `active`, `deprecated`, and `retired`.
|
|
36
|
+
- Replace the legacy `Deprecation: true` header with the RFC 9745 date value `Deprecation: @<unix-timestamp>`. The `Sunset` header continues to use the HTTP-date format defined by RFC 8594.
|
|
37
|
+
|
|
38
|
+
### Migration from 0.3.8
|
|
39
|
+
|
|
40
|
+
Update every `API_VERSION_LIFECYCLE` entry before upgrading:
|
|
41
|
+
|
|
42
|
+
- Set `status` to `active`, `deprecated`, or `retired`. Previously omitted or unrecognized values are now configuration errors.
|
|
43
|
+
- Add `deprecated_at` (an ISO 8601 date or datetime) to every deprecated version. This is the actual deprecation date, not the sunset deadline.
|
|
44
|
+
- Keep or add `sunset` (an ISO 8601 date or datetime) for every retired version.
|
|
45
|
+
- Update clients or tests that expect the non-standard `Deprecation: true` value to parse the RFC 9745 Structured Field Date instead.
|
|
46
|
+
|
|
47
|
+
Example:
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
API_VERSION_LIFECYCLE = {
|
|
51
|
+
1: {
|
|
52
|
+
"status": "deprecated",
|
|
53
|
+
"deprecated_at": "2026-01-01T00:00:00+00:00",
|
|
54
|
+
"sunset": "2027-06-30",
|
|
55
|
+
},
|
|
56
|
+
2: {"status": "active"},
|
|
57
|
+
3: {
|
|
58
|
+
"status": "retired",
|
|
59
|
+
"sunset": "2026-06-30",
|
|
60
|
+
},
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The package runtime minimum remains Python 3.10 and Django 4.2. Django REST Framework remains optional and is not a runtime dependency.
|
|
65
|
+
|
|
11
66
|
## [0.3.8] - 2026-11-16
|
|
12
67
|
|
|
13
68
|
### Fixed
|
|
@@ -120,7 +175,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
120
175
|
- **Comprehensive Integration Testing:** 222+ integration tests covering DRF APIView, GenericAPIView, ViewSets, routers, custom actions, authentication, permissions, and Django-native views.
|
|
121
176
|
- **Enhanced Testing Infrastructure:** Management command tests for `check_versions` and version matrix validation.
|
|
122
177
|
- **Feature Verification Matrix:** Complete traceability matrix documenting 90+ features verified against implementation.
|
|
123
|
-
- **
|
|
178
|
+
- **Historical compatibility report:** [v0.3.8 compatibility evidence](docs/reports/compatibility-0.3.8.md), covering the Python 3.10+, Django 4.2–6.1, and DRF 3.14+ matrix at that release.
|
|
124
179
|
|
|
125
180
|
### Changed
|
|
126
181
|
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: django-api-versioning
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: URL-path API versioning for Django and Django REST Framework with decorator-based endpoint registration and forward route inheritance.
|
|
5
|
+
Author-email: Mojtaba Arvin <ArvinDevDay@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://mojtaba-arvin.github.io/django-api-versioning/
|
|
8
|
+
Project-URL: Documentation, https://mojtaba-arvin.github.io/django-api-versioning/reference/
|
|
9
|
+
Project-URL: Source, https://github.com/mojtaba-arvin/django-api-versioning
|
|
10
|
+
Project-URL: Issues, https://github.com/mojtaba-arvin/django-api-versioning/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CHANGELOG.md
|
|
12
|
+
Project-URL: Security, https://github.com/mojtaba-arvin/django-api-versioning/blob/main/SECURITY.md
|
|
13
|
+
Keywords: django api versioning,django rest framework api versioning,drf versioning,url path api versioning,versioned url routing,endpoint registration,version-specific django views,django-api-versioning
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
21
|
+
Classifier: Framework :: Django
|
|
22
|
+
Classifier: Framework :: Django :: 4.2
|
|
23
|
+
Classifier: Framework :: Django :: 5.2
|
|
24
|
+
Classifier: Framework :: Django :: 6.0
|
|
25
|
+
Classifier: Framework :: Django :: 6.1
|
|
26
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
27
|
+
Classifier: Intended Audience :: Developers
|
|
28
|
+
Classifier: Operating System :: OS Independent
|
|
29
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
30
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
31
|
+
Classifier: Typing :: Typed
|
|
32
|
+
Requires-Python: >=3.10
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
License-File: LICENSE
|
|
35
|
+
Requires-Dist: Django>=4.2
|
|
36
|
+
Provides-Extra: dev
|
|
37
|
+
Requires-Dist: black>=26.10.1; extra == "dev"
|
|
38
|
+
Requires-Dist: flake8>=7.4.1; extra == "dev"
|
|
39
|
+
Requires-Dist: isort>=9.0.2; extra == "dev"
|
|
40
|
+
Requires-Dist: mypy>=2.4.0; extra == "dev"
|
|
41
|
+
Requires-Dist: pytest>=9.2.0; extra == "dev"
|
|
42
|
+
Requires-Dist: pytest-django>=4.14.0; extra == "dev"
|
|
43
|
+
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
|
|
44
|
+
Requires-Dist: pre-commit>=4.7.0; python_version >= "3.11" and extra == "dev"
|
|
45
|
+
Requires-Dist: twine>=7.0.0; extra == "dev"
|
|
46
|
+
Requires-Dist: build>=1.6.1; extra == "dev"
|
|
47
|
+
Requires-Dist: djangorestframework>=3.18; extra == "dev"
|
|
48
|
+
Requires-Dist: tomli>=2.0.1; python_version < "3.11" and extra == "dev"
|
|
49
|
+
Dynamic: license-file
|
|
50
|
+
|
|
51
|
+
<p align="center">
|
|
52
|
+
<a href="https://mojtaba-arvin.github.io/django-api-versioning/">
|
|
53
|
+
<img src="https://raw.githubusercontent.com/mojtaba-arvin/django-api-versioning/main/website/public/favicon.svg" alt="Django API Versioning logo" width="64" height="64">
|
|
54
|
+
</a>
|
|
55
|
+
</p>
|
|
56
|
+
|
|
57
|
+
# Django API Versioning
|
|
58
|
+
|
|
59
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
60
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
61
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini)
|
|
62
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/actions/workflows/tests.yml)
|
|
63
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE)
|
|
64
|
+
|
|
65
|
+
**Version your Django API by endpoint, not by duplicating URL patterns.** Register a view once; unchanged routes carry forward to later API versions, and a newer declaration replaces the implementation from that version onward.
|
|
66
|
+
|
|
67
|
+
[Explore Django API Versioning — documentation, examples, and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) · [Install django-api-versioning from PyPI](https://pypi.org/project/django-api-versioning/)
|
|
68
|
+
|
|
69
|
+
## See how it works
|
|
70
|
+
|
|
71
|
+
Install the package and Django REST Framework:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pip install django-api-versioning djangorestframework
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Declare only the versions where an endpoint's behavior changes:
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from rest_framework.response import Response
|
|
81
|
+
from rest_framework.views import APIView
|
|
82
|
+
|
|
83
|
+
from django_api_versioning import endpoint
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
@endpoint("orders/", version=1, view_name="order-list")
|
|
87
|
+
class OrderListV1(APIView):
|
|
88
|
+
def get(self, request):
|
|
89
|
+
return Response({"total": "19.99"})
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
@endpoint("orders/", version=2, view_name="order-list")
|
|
93
|
+
class OrderListV2(APIView):
|
|
94
|
+
def get(self, request):
|
|
95
|
+
return Response({"total": 1999, "currency": "USD"})
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
With `API_MAX_VERSION = 3`, the generated routes are:
|
|
99
|
+
|
|
100
|
+
| Request | View |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| `GET /api/v1/orders/` | `OrderListV1` |
|
|
103
|
+
| `GET /api/v2/orders/` | `OrderListV2` |
|
|
104
|
+
| `GET /api/v3/orders/` | `OrderListV2` |
|
|
105
|
+
|
|
106
|
+
The v1 view serves v1 until another declaration replaces it. The v2 view then serves v2 and v3. **You write a new view when the endpoint changes—not another copy of every unchanged route.**
|
|
107
|
+
|
|
108
|
+
For the complete setup, including Django settings and URL configuration, see the [Django API Versioning getting-started guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/022-django-api-versioning-how-does-it-work/).
|
|
109
|
+
|
|
110
|
+
## What problem does it solve?
|
|
111
|
+
|
|
112
|
+
In a growing API, only some endpoints change between releases. Manually maintaining a separate URL configuration for every version can repeat registrations and obscure which implementation handles each version.
|
|
113
|
+
|
|
114
|
+
Django API Versioning makes that mapping explicit with `@endpoint`:
|
|
115
|
+
|
|
116
|
+
- **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
|
|
117
|
+
- **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
|
|
118
|
+
- **Explicit registration:** use `versions=[...]` or `ver_range(...)` when an endpoint should exist only in selected versions.
|
|
119
|
+
- **Visibility:** inspect the generated route matrix with `check_versions` and test it with `assert_version_matrix()`.
|
|
120
|
+
|
|
121
|
+
This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
|
|
122
|
+
|
|
123
|
+
## Why use it with Django REST Framework?
|
|
124
|
+
|
|
125
|
+
DRF already provides versioning schemes to identify the requested API version, for example through `request.version`. This package solves a related but different problem: **mapping versioned URL paths to specific view implementations and carrying unchanged registrations forward**.
|
|
126
|
+
|
|
127
|
+
Use DRF's built-in versioning when request-version identification is all you need. Use this package when you want declarative version-to-view routing and an inspectable route matrix. They can be used together; this package does not automatically populate `request.version`.
|
|
128
|
+
|
|
129
|
+
DRF is optional. The package also supports Django function-based and class-based views. For a Django-only project, install just:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
pip install django-api-versioning
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Quick configuration
|
|
136
|
+
|
|
137
|
+
Add the package (and DRF, if used) to `INSTALLED_APPS` and configure the supported version range:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
# settings.py
|
|
141
|
+
INSTALLED_APPS = [
|
|
142
|
+
"rest_framework", # omit when using Django-native views only
|
|
143
|
+
"django_api_versioning",
|
|
144
|
+
]
|
|
145
|
+
|
|
146
|
+
API_MIN_VERSION = 1
|
|
147
|
+
API_MAX_VERSION = 3
|
|
148
|
+
# API_BASE_PATH defaults to "api/v{version}/"
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Import modules containing endpoint declarations before including the generated patterns:
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
# project/urls.py
|
|
155
|
+
from django.urls import include, path
|
|
156
|
+
|
|
157
|
+
from orders import views as _order_views # noqa: F401
|
|
158
|
+
from django_api_versioning.urls import urlpatterns as api_urlpatterns
|
|
159
|
+
|
|
160
|
+
urlpatterns = [
|
|
161
|
+
path("", include(api_urlpatterns)),
|
|
162
|
+
]
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Run the route-matrix check:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
python manage.py check_versions
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Registration options
|
|
172
|
+
|
|
173
|
+
| Declaration | Routes created |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| `@endpoint("orders/", version=2)` | v2 through `API_MAX_VERSION` |
|
|
176
|
+
| `@endpoint("orders/", versions=[1, 3, 5])` | Only v1, v3, and v5 |
|
|
177
|
+
| `@endpoint("health/")` | One unversioned route |
|
|
178
|
+
|
|
179
|
+
For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()` for version-aware URL reversal and `assert_version_matrix()` for regression tests.
|
|
180
|
+
|
|
181
|
+
See the [versioning contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) for exact URL construction, import order, collision precedence, validation, and edge cases.
|
|
182
|
+
|
|
183
|
+
## DRF ViewSet boundary
|
|
184
|
+
|
|
185
|
+
A DRF `ViewSet` or `ModelViewSet` cannot be passed directly to `@endpoint`, because `as_view()` requires an action mapping. You can register a configured callable for an individual route, but this does not create the full router-managed set of list, detail, and custom-action routes. Use DRF's `DefaultRouter` or `SimpleRouter` when you need standard ViewSet routing.
|
|
186
|
+
|
|
187
|
+
See [ViewSet support and limitations](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/).
|
|
188
|
+
|
|
189
|
+
## Requirements
|
|
190
|
+
|
|
191
|
+
- Python 3.10+
|
|
192
|
+
- Django 4.2+
|
|
193
|
+
- Django REST Framework is optional.
|
|
194
|
+
|
|
195
|
+
The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. See [tox.ini](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini) for configured environments and [GitHub Actions](https://github.com/mojtaba-arvin/django-api-versioning/actions) for results tied to a specific commit.
|
|
196
|
+
|
|
197
|
+
## Upgrading to 1.0.0
|
|
198
|
+
|
|
199
|
+
Version 1.0.0 tightened API lifecycle configuration and changed the `Deprecation` response header format. If you use `API_VERSION_LIFECYCLE`:
|
|
200
|
+
|
|
201
|
+
- Every entry must have a `status` of `active`, `deprecated`, or `retired`.
|
|
202
|
+
- A deprecated version must define `deprecated_at` as an ISO 8601 date or datetime.
|
|
203
|
+
- A retired version must define a `sunset` date.
|
|
204
|
+
- The `Deprecation` header now uses the RFC 9745 date-valued Structured Field (for example, `Deprecation: @1767225600`), not the legacy `Deprecation: true` value.
|
|
205
|
+
|
|
206
|
+
For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CHANGELOG.md#100---2026-11-16).
|
|
207
|
+
|
|
208
|
+
## Documentation
|
|
209
|
+
|
|
210
|
+
- [Django API Versioning documentation and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) — overview, examples, lifecycle demonstration, and guides.
|
|
211
|
+
- [API reference](https://mojtaba-arvin.github.io/django-api-versioning/reference/) — settings, decorators, URL reversal, validation, and management commands.
|
|
212
|
+
- [Routing contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) — implementation-backed behavior and limitations.
|
|
213
|
+
- [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
|
|
214
|
+
- [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
|
|
215
|
+
- [Documentation source map](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/README.md).
|
|
216
|
+
|
|
217
|
+
## Contributing
|
|
218
|
+
|
|
219
|
+
Bug reports, corrections, and pull requests are welcome. Read the [contribution guidelines](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/SECURITY.md).
|
|
220
|
+
|
|
221
|
+
## License
|
|
222
|
+
|
|
223
|
+
Released under the [MIT License](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE).
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://mojtaba-arvin.github.io/django-api-versioning/">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/mojtaba-arvin/django-api-versioning/main/website/public/favicon.svg" alt="Django API Versioning logo" width="64" height="64">
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
# Django API Versioning
|
|
8
|
+
|
|
9
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
10
|
+
[](https://pypi.org/project/django-api-versioning/)
|
|
11
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini)
|
|
12
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/actions/workflows/tests.yml)
|
|
13
|
+
[](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE)
|
|
14
|
+
|
|
15
|
+
**Version your Django API by endpoint, not by duplicating URL patterns.** Register a view once; unchanged routes carry forward to later API versions, and a newer declaration replaces the implementation from that version onward.
|
|
16
|
+
|
|
17
|
+
[Explore Django API Versioning — documentation, examples, and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) · [Install django-api-versioning from PyPI](https://pypi.org/project/django-api-versioning/)
|
|
18
|
+
|
|
19
|
+
## See how it works
|
|
20
|
+
|
|
21
|
+
Install the package and Django REST Framework:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install django-api-versioning djangorestframework
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Declare only the versions where an endpoint's behavior changes:
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from rest_framework.response import Response
|
|
31
|
+
from rest_framework.views import APIView
|
|
32
|
+
|
|
33
|
+
from django_api_versioning import endpoint
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@endpoint("orders/", version=1, view_name="order-list")
|
|
37
|
+
class OrderListV1(APIView):
|
|
38
|
+
def get(self, request):
|
|
39
|
+
return Response({"total": "19.99"})
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@endpoint("orders/", version=2, view_name="order-list")
|
|
43
|
+
class OrderListV2(APIView):
|
|
44
|
+
def get(self, request):
|
|
45
|
+
return Response({"total": 1999, "currency": "USD"})
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
With `API_MAX_VERSION = 3`, the generated routes are:
|
|
49
|
+
|
|
50
|
+
| Request | View |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| `GET /api/v1/orders/` | `OrderListV1` |
|
|
53
|
+
| `GET /api/v2/orders/` | `OrderListV2` |
|
|
54
|
+
| `GET /api/v3/orders/` | `OrderListV2` |
|
|
55
|
+
|
|
56
|
+
The v1 view serves v1 until another declaration replaces it. The v2 view then serves v2 and v3. **You write a new view when the endpoint changes—not another copy of every unchanged route.**
|
|
57
|
+
|
|
58
|
+
For the complete setup, including Django settings and URL configuration, see the [Django API Versioning getting-started guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/022-django-api-versioning-how-does-it-work/).
|
|
59
|
+
|
|
60
|
+
## What problem does it solve?
|
|
61
|
+
|
|
62
|
+
In a growing API, only some endpoints change between releases. Manually maintaining a separate URL configuration for every version can repeat registrations and obscure which implementation handles each version.
|
|
63
|
+
|
|
64
|
+
Django API Versioning makes that mapping explicit with `@endpoint`:
|
|
65
|
+
|
|
66
|
+
- **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
|
|
67
|
+
- **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
|
|
68
|
+
- **Explicit registration:** use `versions=[...]` or `ver_range(...)` when an endpoint should exist only in selected versions.
|
|
69
|
+
- **Visibility:** inspect the generated route matrix with `check_versions` and test it with `assert_version_matrix()`.
|
|
70
|
+
|
|
71
|
+
This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
|
|
72
|
+
|
|
73
|
+
## Why use it with Django REST Framework?
|
|
74
|
+
|
|
75
|
+
DRF already provides versioning schemes to identify the requested API version, for example through `request.version`. This package solves a related but different problem: **mapping versioned URL paths to specific view implementations and carrying unchanged registrations forward**.
|
|
76
|
+
|
|
77
|
+
Use DRF's built-in versioning when request-version identification is all you need. Use this package when you want declarative version-to-view routing and an inspectable route matrix. They can be used together; this package does not automatically populate `request.version`.
|
|
78
|
+
|
|
79
|
+
DRF is optional. The package also supports Django function-based and class-based views. For a Django-only project, install just:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
pip install django-api-versioning
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Quick configuration
|
|
86
|
+
|
|
87
|
+
Add the package (and DRF, if used) to `INSTALLED_APPS` and configure the supported version range:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
# settings.py
|
|
91
|
+
INSTALLED_APPS = [
|
|
92
|
+
"rest_framework", # omit when using Django-native views only
|
|
93
|
+
"django_api_versioning",
|
|
94
|
+
]
|
|
95
|
+
|
|
96
|
+
API_MIN_VERSION = 1
|
|
97
|
+
API_MAX_VERSION = 3
|
|
98
|
+
# API_BASE_PATH defaults to "api/v{version}/"
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Import modules containing endpoint declarations before including the generated patterns:
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
# project/urls.py
|
|
105
|
+
from django.urls import include, path
|
|
106
|
+
|
|
107
|
+
from orders import views as _order_views # noqa: F401
|
|
108
|
+
from django_api_versioning.urls import urlpatterns as api_urlpatterns
|
|
109
|
+
|
|
110
|
+
urlpatterns = [
|
|
111
|
+
path("", include(api_urlpatterns)),
|
|
112
|
+
]
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Run the route-matrix check:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
python manage.py check_versions
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Registration options
|
|
122
|
+
|
|
123
|
+
| Declaration | Routes created |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| `@endpoint("orders/", version=2)` | v2 through `API_MAX_VERSION` |
|
|
126
|
+
| `@endpoint("orders/", versions=[1, 3, 5])` | Only v1, v3, and v5 |
|
|
127
|
+
| `@endpoint("health/")` | One unversioned route |
|
|
128
|
+
|
|
129
|
+
For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()` for version-aware URL reversal and `assert_version_matrix()` for regression tests.
|
|
130
|
+
|
|
131
|
+
See the [versioning contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) for exact URL construction, import order, collision precedence, validation, and edge cases.
|
|
132
|
+
|
|
133
|
+
## DRF ViewSet boundary
|
|
134
|
+
|
|
135
|
+
A DRF `ViewSet` or `ModelViewSet` cannot be passed directly to `@endpoint`, because `as_view()` requires an action mapping. You can register a configured callable for an individual route, but this does not create the full router-managed set of list, detail, and custom-action routes. Use DRF's `DefaultRouter` or `SimpleRouter` when you need standard ViewSet routing.
|
|
136
|
+
|
|
137
|
+
See [ViewSet support and limitations](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/).
|
|
138
|
+
|
|
139
|
+
## Requirements
|
|
140
|
+
|
|
141
|
+
- Python 3.10+
|
|
142
|
+
- Django 4.2+
|
|
143
|
+
- Django REST Framework is optional.
|
|
144
|
+
|
|
145
|
+
The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. See [tox.ini](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/tox.ini) for configured environments and [GitHub Actions](https://github.com/mojtaba-arvin/django-api-versioning/actions) for results tied to a specific commit.
|
|
146
|
+
|
|
147
|
+
## Upgrading to 1.0.0
|
|
148
|
+
|
|
149
|
+
Version 1.0.0 tightened API lifecycle configuration and changed the `Deprecation` response header format. If you use `API_VERSION_LIFECYCLE`:
|
|
150
|
+
|
|
151
|
+
- Every entry must have a `status` of `active`, `deprecated`, or `retired`.
|
|
152
|
+
- A deprecated version must define `deprecated_at` as an ISO 8601 date or datetime.
|
|
153
|
+
- A retired version must define a `sunset` date.
|
|
154
|
+
- The `Deprecation` header now uses the RFC 9745 date-valued Structured Field (for example, `Deprecation: @1767225600`), not the legacy `Deprecation: true` value.
|
|
155
|
+
|
|
156
|
+
For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CHANGELOG.md#100---2026-11-16).
|
|
157
|
+
|
|
158
|
+
## Documentation
|
|
159
|
+
|
|
160
|
+
- [Django API Versioning documentation and interactive playground](https://mojtaba-arvin.github.io/django-api-versioning/) — overview, examples, lifecycle demonstration, and guides.
|
|
161
|
+
- [API reference](https://mojtaba-arvin.github.io/django-api-versioning/reference/) — settings, decorators, URL reversal, validation, and management commands.
|
|
162
|
+
- [Routing contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/reference/versioning-contract.md) — implementation-backed behavior and limitations.
|
|
163
|
+
- [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
|
|
164
|
+
- [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
|
|
165
|
+
- [Documentation source map](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/README.md).
|
|
166
|
+
|
|
167
|
+
## Contributing
|
|
168
|
+
|
|
169
|
+
Bug reports, corrections, and pull requests are welcome. Read the [contribution guidelines](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/SECURITY.md).
|
|
170
|
+
|
|
171
|
+
## License
|
|
172
|
+
|
|
173
|
+
Released under the [MIT License](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/LICENSE).
|
{django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/lifecycle.py
RENAMED
|
@@ -42,7 +42,11 @@ class LifecycleMiddleware:
|
|
|
42
42
|
|
|
43
43
|
API_VERSION_LIFECYCLE = {
|
|
44
44
|
1: {"status": "retired", "sunset": "2024-01-01"},
|
|
45
|
-
2: {
|
|
45
|
+
2: {
|
|
46
|
+
"status": "deprecated",
|
|
47
|
+
"deprecated_at": "2026-01-01T00:00:00+00:00",
|
|
48
|
+
"sunset": "2026-06-01",
|
|
49
|
+
},
|
|
46
50
|
3: {"status": "active"},
|
|
47
51
|
}
|
|
48
52
|
"""
|
|
@@ -60,6 +64,12 @@ class LifecycleMiddleware:
|
|
|
60
64
|
if not meta:
|
|
61
65
|
return self.get_response(request)
|
|
62
66
|
|
|
67
|
+
deprecated_at = meta.get("deprecated_at")
|
|
68
|
+
deprecation_date = (
|
|
69
|
+
_parse_lifecycle_date(deprecated_at, "deprecation")
|
|
70
|
+
if deprecated_at
|
|
71
|
+
else None
|
|
72
|
+
)
|
|
63
73
|
sunset = meta.get("sunset")
|
|
64
74
|
sunset_date = _parse_sunset(sunset) if sunset else None
|
|
65
75
|
if sunset_date and _is_past(sunset_date):
|
|
@@ -69,7 +79,14 @@ class LifecycleMiddleware:
|
|
|
69
79
|
|
|
70
80
|
response = self.get_response(request)
|
|
71
81
|
if meta.get("status") == "deprecated":
|
|
72
|
-
|
|
82
|
+
if deprecation_date is not None:
|
|
83
|
+
response["Deprecation"] = _to_structured_field_date(deprecation_date)
|
|
84
|
+
else:
|
|
85
|
+
logger.warning(
|
|
86
|
+
"Deprecated API version %s has no valid deprecated_at date; "
|
|
87
|
+
"omitting the Deprecation header.",
|
|
88
|
+
version,
|
|
89
|
+
)
|
|
73
90
|
if sunset_date:
|
|
74
91
|
response["Sunset"] = _to_http_date(sunset_date)
|
|
75
92
|
return response
|
|
@@ -147,14 +164,19 @@ def _extract_version_from_path(request: HttpRequest) -> int | None:
|
|
|
147
164
|
|
|
148
165
|
def _parse_sunset(value: Any) -> datetime | None:
|
|
149
166
|
"""Parse a configured sunset value and normalize it to UTC."""
|
|
167
|
+
return _parse_lifecycle_date(value, "sunset")
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _parse_lifecycle_date(value: Any, field_name: str) -> datetime | None:
|
|
171
|
+
"""Parse an ISO 8601 lifecycle date and normalize it to UTC."""
|
|
150
172
|
if not isinstance(value, str):
|
|
151
|
-
logger.warning("Invalid
|
|
173
|
+
logger.warning("Invalid %s date %r; ignoring.", field_name, value)
|
|
152
174
|
return None
|
|
153
175
|
|
|
154
176
|
try:
|
|
155
177
|
parsed = datetime.fromisoformat(value)
|
|
156
178
|
except ValueError:
|
|
157
|
-
logger.warning("Invalid
|
|
179
|
+
logger.warning("Invalid %s date %r; ignoring.", field_name, value)
|
|
158
180
|
return None
|
|
159
181
|
|
|
160
182
|
if parsed.tzinfo is None:
|
|
@@ -168,3 +190,8 @@ def _is_past(date: datetime) -> bool:
|
|
|
168
190
|
|
|
169
191
|
def _to_http_date(date: datetime) -> str:
|
|
170
192
|
return date.strftime("%a, %d %b %Y %H:%M:%S GMT")
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def _to_structured_field_date(date: datetime) -> str:
|
|
196
|
+
"""Serialize an RFC 9745 Date as an RFC 9651 Structured Field Date."""
|
|
197
|
+
return f"@{int(date.timestamp())}"
|
{django_api_versioning-0.3.8 → django_api_versioning-1.0.1}/django_api_versioning/settings.py
RENAMED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import logging
|
|
2
2
|
from dataclasses import dataclass, field
|
|
3
|
+
from datetime import datetime
|
|
3
4
|
from string import Formatter
|
|
4
5
|
from typing import Any, Callable
|
|
5
6
|
|
|
@@ -150,6 +151,40 @@ class APISettings:
|
|
|
150
151
|
f"Lifecycle metadata for version {version} must be a dict."
|
|
151
152
|
)
|
|
152
153
|
|
|
154
|
+
status = meta.get("status")
|
|
155
|
+
if status not in {"active", "deprecated", "retired"}:
|
|
156
|
+
raise VersioningError(
|
|
157
|
+
f"Lifecycle status for version {version} must be one of "
|
|
158
|
+
"'active', 'deprecated', or 'retired'."
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
if status == "deprecated" and "deprecated_at" not in meta:
|
|
162
|
+
raise VersioningError(
|
|
163
|
+
f"Deprecated API version {version} requires a "
|
|
164
|
+
"'deprecated_at' ISO 8601 date or datetime."
|
|
165
|
+
)
|
|
166
|
+
if status == "retired" and "sunset" not in meta:
|
|
167
|
+
raise VersioningError(
|
|
168
|
+
f"Retired API version {version} requires a 'sunset' date."
|
|
169
|
+
)
|
|
170
|
+
|
|
171
|
+
for field_name in ("deprecated_at", "sunset"):
|
|
172
|
+
if field_name not in meta:
|
|
173
|
+
continue
|
|
174
|
+
value = meta[field_name]
|
|
175
|
+
if not isinstance(value, str):
|
|
176
|
+
raise VersioningError(
|
|
177
|
+
f"Lifecycle {field_name} for version {version} "
|
|
178
|
+
"must be an ISO 8601 string."
|
|
179
|
+
)
|
|
180
|
+
try:
|
|
181
|
+
datetime.fromisoformat(value)
|
|
182
|
+
except ValueError as exc:
|
|
183
|
+
raise VersioningError(
|
|
184
|
+
f"Lifecycle {field_name} for version {version} "
|
|
185
|
+
"must be a valid ISO 8601 date or datetime."
|
|
186
|
+
) from exc
|
|
187
|
+
|
|
153
188
|
def _validate_channels(self) -> None:
|
|
154
189
|
allowed = {"path", "header", "query"}
|
|
155
190
|
if not isinstance(self.API_VERSIONING_CHANNELS, list):
|