django-api-versioning 1.0.1__tar.gz → 1.2.0__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-1.0.1 → django_api_versioning-1.2.0}/CHANGELOG.md +58 -1
- {django_api_versioning-1.0.1/django_api_versioning.egg-info → django_api_versioning-1.2.0}/PKG-INFO +58 -11
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/README.md +56 -9
- django_api_versioning-1.2.0/django_api_versioning/__init__.py +10 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/decorators.py +81 -0
- django_api_versioning-1.2.0/django_api_versioning/lifecycle.py +283 -0
- django_api_versioning-1.2.0/django_api_versioning/lifecycle_metadata.py +62 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/management/commands/check_versions.py +25 -3
- django_api_versioning-1.2.0/django_api_versioning/management/commands/migrate_endpoints.py +433 -0
- django_api_versioning-1.2.0/django_api_versioning/registry.py +684 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/reverse.py +15 -8
- django_api_versioning-1.2.0/django_api_versioning/routers.py +433 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/settings.py +44 -3
- django_api_versioning-1.2.0/django_api_versioning/spectacular.py +75 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/testing.py +51 -17
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0/django_api_versioning.egg-info}/PKG-INFO +58 -11
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/SOURCES.txt +7 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/requires.txt +1 -1
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/pyproject.toml +2 -2
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/requirements-dev.txt +1 -1
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/conftest.py +2 -2
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_decorators.py +140 -2
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_lifecycle.py +100 -14
- django_api_versioning-1.2.0/tests/test_lifecycle_integration.py +560 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_management_commands.py +294 -0
- django_api_versioning-1.2.0/tests/test_registry.py +1138 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_reverse.py +46 -1
- django_api_versioning-1.2.0/tests/test_route_removal.py +281 -0
- django_api_versioning-1.2.0/tests/test_routers.py +491 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_settings.py +76 -1
- django_api_versioning-1.2.0/tests/test_spectacular.py +172 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_testing_utils.py +45 -0
- django_api_versioning-1.0.1/django_api_versioning/__init__.py +0 -4
- django_api_versioning-1.0.1/django_api_versioning/lifecycle.py +0 -197
- django_api_versioning-1.0.1/django_api_versioning/management/commands/migrate_endpoints.py +0 -249
- django_api_versioning-1.0.1/django_api_versioning/registry.py +0 -195
- django_api_versioning-1.0.1/tests/test_registry.py +0 -464
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/LICENSE +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/MANIFEST.in +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/channels.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/exceptions.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/management/__init__.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/management/commands/__init__.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/py.typed +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/urls.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/dependency_links.txt +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/top_level.txt +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/pytest.ini +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/requirements.txt +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/setup.cfg +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/__init__.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/settings.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_channels.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_channels_extra.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_distribution_contents.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_exceptions.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_segment_model.py +0 -0
- {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_urls.py +0 -0
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
|
|
2
1
|
# Changelog
|
|
3
2
|
|
|
4
3
|
All notable changes to this project will be documented in this file.
|
|
@@ -8,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
8
7
|
|
|
9
8
|
## [Unreleased]
|
|
10
9
|
|
|
10
|
+
## [1.2.0] - 2026-11-19
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Add explicit endpoint removal through `remove_endpoint()` and `VersionedRouter.remove()`. Removed routes remain available in earlier API versions, disappear from runtime routing and URL reversal at the removal boundary, and may be explicitly reintroduced by a later version declaration.
|
|
15
|
+
- Add endpoint-level lifecycle declarations through `set_endpoint_lifecycle()` and `VersionedRouter.set_lifecycle()`. Matching requests receive version-scoped RFC 9745 `Deprecation` and RFC 8594 `Sunset` headers. The optional drf-spectacular adapter marks deprecated operations with OpenAPI `deprecated: true`. Endpoint-level past-Sunset metadata remains headers-only; version-wide retirement keeps its existing 410 behavior.
|
|
16
|
+
- Add the optional `EndpointLifecycleAutoSchema` integration for decorator-backed DRF endpoints and VersionedRouter operations. drf-spectacular remains an optional integration dependency and is not imported by the package core.
|
|
17
|
+
|
|
18
|
+
### Fixed
|
|
19
|
+
|
|
20
|
+
- Reject duplicate generated route patterns registered by different `VersionedRouter` instances instead of silently allowing the later router to replace the earlier ViewSet in the shared registry.
|
|
21
|
+
- Validate non-string and unhashable `API_VERSION_LIFECYCLE` status values as `VersioningError` instead of leaking a raw `TypeError`.
|
|
22
|
+
|
|
23
|
+
### Compatibility
|
|
24
|
+
|
|
25
|
+
- No migration is required for existing 1.1.0 users. The existing URL-path routing contract and the optional nature of Django REST Framework are unchanged.
|
|
26
|
+
- Applications that registered colliding generated route patterns across independent `VersionedRouter` instances will now receive `VersioningError` instead of relying on last-writer replacement. Use distinct route prefixes and outer namespaces; duplicate generated patterns are not a supported dispatch contract.
|
|
27
|
+
- Header/query/tenant-based version negotiation remains unsupported; reserved settings do not activate additional negotiation channels.
|
|
28
|
+
|
|
29
|
+
### Verification
|
|
30
|
+
|
|
31
|
+
- Release verification is tied to the annotated `v1.2.0` tag and its GitHub Actions run. The full Python/Django/DRF matrix, executable versioned OpenAPI consumer contract, wheel/sdist validation, isolated installed-wheel smoke test, and distribution-content checks are required before publication.
|
|
32
|
+
|
|
33
|
+
### Documentation
|
|
34
|
+
|
|
35
|
+
- Update the canonical routing contract, public API reference, README, website, and ViewSet/lifecycle/OpenAPI design records for the 1.2.0 release boundary.
|
|
36
|
+
|
|
37
|
+
## [1.1.0] - 2026-11-18
|
|
38
|
+
|
|
39
|
+
### Added
|
|
40
|
+
|
|
41
|
+
- Add the optional `VersionedRouter` integration for DRF `SimpleRouter` ViewSets, preserving standard routes, custom actions, callback metadata, and per-route version inheritance.
|
|
42
|
+
- Add `VersionedRouterVersioning` to expose the concrete router namespace as DRF's `request.version` and keep `reverse_action()` and hyperlinked serializer URLs within the active version.
|
|
43
|
+
- Preserve regex-backed and path-converter URLPatterns in the registry; extend `api_reverse()` to reverse DRF regex routes through Django's URL resolver and reject duplicate names within one concrete version.
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
|
|
47
|
+
- Extend lifecycle version extraction to recognize the configured API base path below parent URL prefixes, so nested URL includes retain deprecation and sunset behavior.
|
|
48
|
+
- Clarify that `API_VERSIONING_CHANNELS` and `API_EFFECTIVE_VERSION_RESOLVER` are reserved settings with no runtime effect; log a warning when non-default values are configured.
|
|
49
|
+
|
|
50
|
+
### Fixed
|
|
51
|
+
|
|
52
|
+
- Make `VersionedRouterVersioning` interoperable with drf-spectacular's namespace version filtering while preserving package-specific reversal; avoid double namespace qualification and defer SimpleRouter import to prevent a DRF initialization cycle.
|
|
53
|
+
- Add opt-in strict route-matrix assertions that reject empty registries and missing committed snapshots while preserving existing default behavior; add `check_versions --fail-on-empty` and resolve root and included URLconfs before inspecting registered endpoints.
|
|
54
|
+
- Reject deprecated or retired lifecycle configurations where `sunset` is earlier than `deprecated_at`, comparing dates as UTC instants and interpreting timezone-naive ISO 8601 values as UTC.
|
|
55
|
+
- `LifecycleMiddleware` now sends the `Sunset` header (and `Deprecation`, when `deprecated_at` is configured) for `retired` versions whose `sunset` date is still in the future. Previously these responses carried no lifecycle headers even though the version was about to be removed. Retired versions with a past `sunset` still return `410 Gone`, and `active` and unknown versions are unchanged.
|
|
56
|
+
|
|
57
|
+
### Testing
|
|
58
|
+
|
|
59
|
+
- Pin Django REST Framework independently in tox for each Django compatibility line: DRF 3.17.2 for Django 4.2 and DRF 3.18.x for Django 5.2, 6.0, and 6.1. The compatibility matrix verifies these tested Django/DRF combinations.
|
|
60
|
+
- Verify the built wheel in isolation, distribution contents, and website artifacts as part of the release workflow.
|
|
61
|
+
|
|
62
|
+
### Documentation
|
|
63
|
+
|
|
64
|
+
- Add a request-version-resolution architecture decision that documents the current path-only contract, research findings, and implementation gates for any future negotiation support.
|
|
65
|
+
- Clarify that Django 4.2 remains in the 1.x compatibility matrix for existing installations but is no longer a supported Django security-release line; recommend a currently supported Django version for new deployments.
|
|
66
|
+
- Document the VersionedRouter setup, per-route inheritance, namespace-aware reversal, and the explicit boundaries of the initial SimpleRouter integration.
|
|
67
|
+
|
|
11
68
|
## [1.0.1] - 2026-11-17
|
|
12
69
|
|
|
13
70
|
### Documentation
|
{django_api_versioning-1.0.1/django_api_versioning.egg-info → django_api_versioning-1.2.0}/PKG-INFO
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: django-api-versioning
|
|
3
|
-
Version: 1.0
|
|
3
|
+
Version: 1.2.0
|
|
4
4
|
Summary: URL-path API versioning for Django and Django REST Framework with decorator-based endpoint registration and forward route inheritance.
|
|
5
5
|
Author-email: Mojtaba Arvin <ArvinDevDay@gmail.com>
|
|
6
6
|
License-Expression: MIT
|
|
@@ -45,7 +45,7 @@ Requires-Dist: pre-commit>=4.7.0; python_version >= "3.11" and extra == "dev"
|
|
|
45
45
|
Requires-Dist: twine>=7.0.0; extra == "dev"
|
|
46
46
|
Requires-Dist: build>=1.6.1; extra == "dev"
|
|
47
47
|
Requires-Dist: djangorestframework>=3.18; extra == "dev"
|
|
48
|
-
Requires-Dist: tomli>=2.0
|
|
48
|
+
Requires-Dist: tomli>=2.5.0; python_version < "3.11" and extra == "dev"
|
|
49
49
|
Dynamic: license-file
|
|
50
50
|
|
|
51
51
|
<p align="center">
|
|
@@ -116,17 +116,19 @@ Django API Versioning makes that mapping explicit with `@endpoint`:
|
|
|
116
116
|
- **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
|
|
117
117
|
- **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
|
|
118
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
|
|
119
|
+
- **Visibility:** inspect the generated route matrix with `python manage.py check_versions --fail-on-empty` and guard it with `assert_version_matrix(snapshot=".version_matrix.json", strict=True)`.
|
|
120
120
|
|
|
121
121
|
This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
|
|
122
122
|
|
|
123
|
+
**Included in the upcoming 1.2.0 release (not yet published):** Explicit endpoint removal is implemented in the repository and will be included in the next release; it is not part of the published `1.1.0` artifact. Use `remove_endpoint("orders/", from_version=3)` for decorator endpoints or `VersionedRouter.remove(prefix, route_name, from_version=...)` for one generated DRF action. Earlier versions retain the route, removed versions return 404, and a later source declaration can explicitly reintroduce it. These APIs are documented in the [endpoint-removal contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/endpoint-removal.md). The 1.2.0 release candidate also adds `set_endpoint_lifecycle()` for decorator endpoints and `VersionedRouter.set_lifecycle()` for DRF operations. The optional `EndpointLifecycleAutoSchema` integration marks matching deprecated OpenAPI operations; these endpoint-level lifecycle APIs are also included in the upcoming `1.2.0` release, pending publication. See the [endpoint lifecycle design](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/endpoint-lifecycle.md).
|
|
124
|
+
|
|
123
125
|
## Why use it with Django REST Framework?
|
|
124
126
|
|
|
125
|
-
DRF already provides
|
|
127
|
+
DRF already provides request-version identification and ViewSet route generation. Django API Versioning adds the missing connection between those capabilities: **mapping each concrete API version to the correct ViewSet implementation while inheriting unchanged routes independently**.
|
|
126
128
|
|
|
127
|
-
|
|
129
|
+
For Django-native function-based and class-based views, use `@endpoint`. For DRF `ViewSet` and `ModelViewSet` classes, use the optional `VersionedRouter`. It delegates route generation to DRF's `SimpleRouter`, preserving standard actions, custom `@action` routes, lookup behavior, and action-level configuration.
|
|
128
130
|
|
|
129
|
-
DRF
|
|
131
|
+
The optional `VersionedRouterVersioning` adapter exposes the selected version as DRF's `request.version` and keeps `reverse_action()` and hyperlinked serializers version-aware. DRF remains optional for projects that use only Django-native views. For those projects, install just:
|
|
130
132
|
|
|
131
133
|
```bash
|
|
132
134
|
pip install django-api-versioning
|
|
@@ -180,19 +182,63 @@ For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()
|
|
|
180
182
|
|
|
181
183
|
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
184
|
|
|
183
|
-
## DRF
|
|
185
|
+
## Versioned DRF ViewSets
|
|
186
|
+
|
|
187
|
+
Use `VersionedRouter` when you want DRF's normal ViewSet workflow with version-aware implementation dispatch:
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
# settings.py — configure before importing ViewSet modules
|
|
191
|
+
REST_FRAMEWORK = {
|
|
192
|
+
"DEFAULT_VERSIONING_CLASS": (
|
|
193
|
+
"django_api_versioning.routers.VersionedRouterVersioning"
|
|
194
|
+
),
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
# project/urls.py
|
|
200
|
+
from django_api_versioning.routers import VersionedRouter
|
|
201
|
+
from orders.views import OrderViewSetV1, OrderViewSetV2
|
|
202
|
+
|
|
203
|
+
router = VersionedRouter()
|
|
204
|
+
router.register("orders", OrderViewSetV1, version=1, basename="order")
|
|
205
|
+
router.register("orders", OrderViewSetV2, version=2, basename="order")
|
|
206
|
+
|
|
207
|
+
urlpatterns = router.urls
|
|
208
|
+
```
|
|
184
209
|
|
|
185
|
-
|
|
210
|
+
With `API_MAX_VERSION = 3`, the routes are served at `/api/v1/orders/`, `/api/v2/orders/`, and `/api/v3/orders/`. V2 replaces only the generated routes it declares. If a custom action exists in V1 but is not redeclared in V2, that action remains inherited in v2 and v3 while list/detail can use V2.
|
|
186
211
|
|
|
187
|
-
|
|
212
|
+
For endpoints that should exist only in selected versions, pass `versions=[1, 3]`; v2 remains a 404. The router also supports `trailing_slash=False` and `use_regex_path=False` for Django path converters.
|
|
213
|
+
|
|
214
|
+
The adapter is required when ViewSets need `request.version`, `reverse_action()`, or hyperlinked serializer support. You can configure it globally through `REST_FRAMEWORK` as shown above, or set `versioning_class = VersionedRouterVersioning` on selected ViewSets.
|
|
215
|
+
|
|
216
|
+
**Scope:** the initial integration supports DRF `SimpleRouter`; it does not claim `DefaultRouter` API-root or format-suffix parity. It does not transform serializers or response payloads. A route omitted from a later ViewSet remains inherited; remove it explicitly with `VersionedRouter.remove()` (included in the upcoming 1.2.0 release, not in the published `1.1.0` artifact). Header/query/tenant negotiation is not enabled by the reserved settings and remains a separate design decision.
|
|
217
|
+
|
|
218
|
+
For DRF installation, use a version compatible with your Django release:
|
|
219
|
+
```bash
|
|
220
|
+
# Django 4.2 compatibility
|
|
221
|
+
pip install "djangorestframework>=3.17.2,<3.18"
|
|
222
|
+
|
|
223
|
+
# Django 5.2, 6.0, or 6.1
|
|
224
|
+
pip install "djangorestframework>=3.18.3,<3.19"
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
See the [Versioned DRF ViewSet guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/) for route inheritance, reversal, namespaces, and the exact integration boundary.
|
|
228
|
+
|
|
229
|
+
For the repository's executable OpenAPI workflow, see the [versioned OpenAPI contract example](https://github.com/mojtaba-arvin/django-api-versioning/tree/main/examples/openapi_contract). This consumer example and its `oasdiff` CI gate were added after the published release; they are repository-level tooling, not part of the package wheel, and do not make drf-spectacular or oasdiff runtime dependencies.
|
|
188
230
|
|
|
189
231
|
## Requirements
|
|
190
232
|
|
|
191
233
|
- Python 3.10+
|
|
192
|
-
- Django 4.2+
|
|
234
|
+
- Django 4.2+ (retained for compatibility with existing 1.x installations)
|
|
193
235
|
- Django REST Framework is optional.
|
|
194
236
|
|
|
195
|
-
|
|
237
|
+
**For new deployments, use a currently supported Django release, preferably Django 5.2 LTS or later.** Django 4.2 reached the end of extended support on 7 April 2026. It remains in this package's compatibility matrix for existing projects, but no longer receives Django security fixes. See [Django's supported versions](https://www.djangoproject.com/download/#supported-versions).
|
|
238
|
+
|
|
239
|
+
The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. DRF is tested against versions supported by each upstream combination: DRF 3.17.2 on Django 4.2, and DRF 3.18.x on Django 5.2, 6.0, and 6.1. DRF 3.18 dropped Django 4.2, so these lines are deliberately pinned separately rather than relying on an unbounded latest version.
|
|
240
|
+
|
|
241
|
+
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
242
|
|
|
197
243
|
## Upgrading to 1.0.0
|
|
198
244
|
|
|
@@ -213,6 +259,7 @@ For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/
|
|
|
213
259
|
- [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
|
|
214
260
|
- [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
|
|
215
261
|
- [Documentation source map](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/README.md).
|
|
262
|
+
- [Request version resolution decision](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/request-version-resolution.md) — why path-based handler selection remains the current contract and what a safe future negotiation design requires.
|
|
216
263
|
|
|
217
264
|
## Contributing
|
|
218
265
|
|
|
@@ -66,17 +66,19 @@ Django API Versioning makes that mapping explicit with `@endpoint`:
|
|
|
66
66
|
- **Forward route inheritance:** `version=1` registers the endpoint from v1 through `API_MAX_VERSION`.
|
|
67
67
|
- **Version-specific replacement:** a v2 declaration takes over from v2 onward; earlier versions retain the v1 implementation.
|
|
68
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
|
|
69
|
+
- **Visibility:** inspect the generated route matrix with `python manage.py check_versions --fail-on-empty` and guard it with `assert_version_matrix(snapshot=".version_matrix.json", strict=True)`.
|
|
70
70
|
|
|
71
71
|
This is inheritance of route registrations, not automatic backward compatibility. Your application remains responsible for response schemas, business behavior, and compatibility tests.
|
|
72
72
|
|
|
73
|
+
**Included in the upcoming 1.2.0 release (not yet published):** Explicit endpoint removal is implemented in the repository and will be included in the next release; it is not part of the published `1.1.0` artifact. Use `remove_endpoint("orders/", from_version=3)` for decorator endpoints or `VersionedRouter.remove(prefix, route_name, from_version=...)` for one generated DRF action. Earlier versions retain the route, removed versions return 404, and a later source declaration can explicitly reintroduce it. These APIs are documented in the [endpoint-removal contract](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/endpoint-removal.md). The 1.2.0 release candidate also adds `set_endpoint_lifecycle()` for decorator endpoints and `VersionedRouter.set_lifecycle()` for DRF operations. The optional `EndpointLifecycleAutoSchema` integration marks matching deprecated OpenAPI operations; these endpoint-level lifecycle APIs are also included in the upcoming `1.2.0` release, pending publication. See the [endpoint lifecycle design](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/endpoint-lifecycle.md).
|
|
74
|
+
|
|
73
75
|
## Why use it with Django REST Framework?
|
|
74
76
|
|
|
75
|
-
DRF already provides
|
|
77
|
+
DRF already provides request-version identification and ViewSet route generation. Django API Versioning adds the missing connection between those capabilities: **mapping each concrete API version to the correct ViewSet implementation while inheriting unchanged routes independently**.
|
|
76
78
|
|
|
77
|
-
|
|
79
|
+
For Django-native function-based and class-based views, use `@endpoint`. For DRF `ViewSet` and `ModelViewSet` classes, use the optional `VersionedRouter`. It delegates route generation to DRF's `SimpleRouter`, preserving standard actions, custom `@action` routes, lookup behavior, and action-level configuration.
|
|
78
80
|
|
|
79
|
-
DRF
|
|
81
|
+
The optional `VersionedRouterVersioning` adapter exposes the selected version as DRF's `request.version` and keeps `reverse_action()` and hyperlinked serializers version-aware. DRF remains optional for projects that use only Django-native views. For those projects, install just:
|
|
80
82
|
|
|
81
83
|
```bash
|
|
82
84
|
pip install django-api-versioning
|
|
@@ -130,19 +132,63 @@ For an inclusive range, use `ver_range(1, 3)`. Other APIs include `api_reverse()
|
|
|
130
132
|
|
|
131
133
|
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
134
|
|
|
133
|
-
## DRF
|
|
135
|
+
## Versioned DRF ViewSets
|
|
136
|
+
|
|
137
|
+
Use `VersionedRouter` when you want DRF's normal ViewSet workflow with version-aware implementation dispatch:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
# settings.py — configure before importing ViewSet modules
|
|
141
|
+
REST_FRAMEWORK = {
|
|
142
|
+
"DEFAULT_VERSIONING_CLASS": (
|
|
143
|
+
"django_api_versioning.routers.VersionedRouterVersioning"
|
|
144
|
+
),
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
# project/urls.py
|
|
150
|
+
from django_api_versioning.routers import VersionedRouter
|
|
151
|
+
from orders.views import OrderViewSetV1, OrderViewSetV2
|
|
152
|
+
|
|
153
|
+
router = VersionedRouter()
|
|
154
|
+
router.register("orders", OrderViewSetV1, version=1, basename="order")
|
|
155
|
+
router.register("orders", OrderViewSetV2, version=2, basename="order")
|
|
156
|
+
|
|
157
|
+
urlpatterns = router.urls
|
|
158
|
+
```
|
|
134
159
|
|
|
135
|
-
|
|
160
|
+
With `API_MAX_VERSION = 3`, the routes are served at `/api/v1/orders/`, `/api/v2/orders/`, and `/api/v3/orders/`. V2 replaces only the generated routes it declares. If a custom action exists in V1 but is not redeclared in V2, that action remains inherited in v2 and v3 while list/detail can use V2.
|
|
136
161
|
|
|
137
|
-
|
|
162
|
+
For endpoints that should exist only in selected versions, pass `versions=[1, 3]`; v2 remains a 404. The router also supports `trailing_slash=False` and `use_regex_path=False` for Django path converters.
|
|
163
|
+
|
|
164
|
+
The adapter is required when ViewSets need `request.version`, `reverse_action()`, or hyperlinked serializer support. You can configure it globally through `REST_FRAMEWORK` as shown above, or set `versioning_class = VersionedRouterVersioning` on selected ViewSets.
|
|
165
|
+
|
|
166
|
+
**Scope:** the initial integration supports DRF `SimpleRouter`; it does not claim `DefaultRouter` API-root or format-suffix parity. It does not transform serializers or response payloads. A route omitted from a later ViewSet remains inherited; remove it explicitly with `VersionedRouter.remove()` (included in the upcoming 1.2.0 release, not in the published `1.1.0` artifact). Header/query/tenant negotiation is not enabled by the reserved settings and remains a separate design decision.
|
|
167
|
+
|
|
168
|
+
For DRF installation, use a version compatible with your Django release:
|
|
169
|
+
```bash
|
|
170
|
+
# Django 4.2 compatibility
|
|
171
|
+
pip install "djangorestframework>=3.17.2,<3.18"
|
|
172
|
+
|
|
173
|
+
# Django 5.2, 6.0, or 6.1
|
|
174
|
+
pip install "djangorestframework>=3.18.3,<3.19"
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
See the [Versioned DRF ViewSet guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/) for route inheritance, reversal, namespaces, and the exact integration boundary.
|
|
178
|
+
|
|
179
|
+
For the repository's executable OpenAPI workflow, see the [versioned OpenAPI contract example](https://github.com/mojtaba-arvin/django-api-versioning/tree/main/examples/openapi_contract). This consumer example and its `oasdiff` CI gate were added after the published release; they are repository-level tooling, not part of the package wheel, and do not make drf-spectacular or oasdiff runtime dependencies.
|
|
138
180
|
|
|
139
181
|
## Requirements
|
|
140
182
|
|
|
141
183
|
- Python 3.10+
|
|
142
|
-
- Django 4.2+
|
|
184
|
+
- Django 4.2+ (retained for compatibility with existing 1.x installations)
|
|
143
185
|
- Django REST Framework is optional.
|
|
144
186
|
|
|
145
|
-
|
|
187
|
+
**For new deployments, use a currently supported Django release, preferably Django 5.2 LTS or later.** Django 4.2 reached the end of extended support on 7 April 2026. It remains in this package's compatibility matrix for existing projects, but no longer receives Django security fixes. See [Django's supported versions](https://www.djangoproject.com/download/#supported-versions).
|
|
188
|
+
|
|
189
|
+
The configured CI matrix covers selected combinations of Python 3.10–3.15 and Django 4.2, 5.2, 6.0, and 6.1. DRF is tested against versions supported by each upstream combination: DRF 3.17.2 on Django 4.2, and DRF 3.18.x on Django 5.2, 6.0, and 6.1. DRF 3.18 dropped Django 4.2, so these lines are deliberately pinned separately rather than relying on an unbounded latest version.
|
|
190
|
+
|
|
191
|
+
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
192
|
|
|
147
193
|
## Upgrading to 1.0.0
|
|
148
194
|
|
|
@@ -163,6 +209,7 @@ For migration steps, see the [1.0.0 changelog](https://github.com/mojtaba-arvin/
|
|
|
163
209
|
- [DRF integration guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/013-drf-version-negotiation-vs-endpoint-registration/).
|
|
164
210
|
- [Python and Django compatibility guide](https://mojtaba-arvin.github.io/django-api-versioning/articles/024-django-api-versioning-supported-django-python-versions/).
|
|
165
211
|
- [Documentation source map](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/README.md).
|
|
212
|
+
- [Request version resolution decision](https://github.com/mojtaba-arvin/django-api-versioning/blob/main/docs/design/request-version-resolution.md) — why path-based handler selection remains the current contract and what a safe future negotiation design requires.
|
|
166
213
|
|
|
167
214
|
## Contributing
|
|
168
215
|
|
{django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/decorators.py
RENAMED
|
@@ -84,6 +84,14 @@ def endpoint(
|
|
|
84
84
|
# Calculate logical endpoint ID from unversioned path
|
|
85
85
|
logical_endpoint = f"{app_name_part}{postfix}"
|
|
86
86
|
|
|
87
|
+
# The schema adapter for URLPathVersioning has no ResolverMatch. Carry
|
|
88
|
+
# the stable decorator identity on the view class, not on callback
|
|
89
|
+
# identity, so schema introspection can resolve it through the registry.
|
|
90
|
+
setattr(view, registry._LOGICAL_ENDPOINT_ATTR, logical_endpoint)
|
|
91
|
+
view_class = getattr(view, "cls", None)
|
|
92
|
+
if isinstance(view_class, type):
|
|
93
|
+
setattr(view_class, registry._LOGICAL_ENDPOINT_ATTR, logical_endpoint)
|
|
94
|
+
|
|
87
95
|
def _register_route(ver: int | None, source_version: int | None) -> None:
|
|
88
96
|
"""Helper function to register a route in the registry."""
|
|
89
97
|
if ver is None:
|
|
@@ -132,6 +140,61 @@ def endpoint(
|
|
|
132
140
|
return decorator
|
|
133
141
|
|
|
134
142
|
|
|
143
|
+
def set_endpoint_lifecycle(
|
|
144
|
+
postfix: str,
|
|
145
|
+
*,
|
|
146
|
+
version: int,
|
|
147
|
+
app_name: str | None = None,
|
|
148
|
+
methods: list[str] | None = None,
|
|
149
|
+
deprecated_at: str | None = None,
|
|
150
|
+
sunset: str | None = None,
|
|
151
|
+
) -> None:
|
|
152
|
+
"""Declare lifecycle dates for one concrete decorator endpoint version.
|
|
153
|
+
|
|
154
|
+
Unlike ``endpoint(version=N)``, this declaration applies only to the
|
|
155
|
+
explicit concrete ``version``. Omitting ``methods`` applies to every
|
|
156
|
+
HTTP method on the logical endpoint; providing methods narrows the scope.
|
|
157
|
+
"""
|
|
158
|
+
if not isinstance(postfix, str):
|
|
159
|
+
raise TypeError("postfix must be a string.")
|
|
160
|
+
if postfix.startswith("/"):
|
|
161
|
+
raise VersioningError("postfix must be relative and must not start with '/'.")
|
|
162
|
+
if app_name is not None and not isinstance(app_name, str):
|
|
163
|
+
raise TypeError("app_name must be a string or None.")
|
|
164
|
+
|
|
165
|
+
app_name_part = f"{app_name}/" if app_name else ""
|
|
166
|
+
logical_endpoint = f"{app_name_part}{postfix}"
|
|
167
|
+
|
|
168
|
+
if methods is None:
|
|
169
|
+
registry.register_endpoint_lifecycle(
|
|
170
|
+
logical_endpoint,
|
|
171
|
+
version,
|
|
172
|
+
deprecated_at=deprecated_at,
|
|
173
|
+
sunset=sunset,
|
|
174
|
+
)
|
|
175
|
+
return
|
|
176
|
+
|
|
177
|
+
if not isinstance(methods, list) or not methods:
|
|
178
|
+
raise VersioningError("methods must be a non-empty list of HTTP methods.")
|
|
179
|
+
normalized_methods = [
|
|
180
|
+
method.strip().upper() if isinstance(method, str) else method
|
|
181
|
+
for method in methods
|
|
182
|
+
]
|
|
183
|
+
if any(not isinstance(method, str) or not method for method in normalized_methods):
|
|
184
|
+
raise VersioningError("methods must contain non-empty HTTP method strings.")
|
|
185
|
+
if len(set(normalized_methods)) != len(normalized_methods):
|
|
186
|
+
raise VersioningError("methods must not contain duplicates.")
|
|
187
|
+
|
|
188
|
+
for method in normalized_methods:
|
|
189
|
+
registry.register_endpoint_lifecycle(
|
|
190
|
+
logical_endpoint,
|
|
191
|
+
version,
|
|
192
|
+
method=method,
|
|
193
|
+
deprecated_at=deprecated_at,
|
|
194
|
+
sunset=sunset,
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
|
|
135
198
|
def _validate_version(version: int, max_version: int) -> None:
|
|
136
199
|
if isinstance(version, bool) or not isinstance(version, int):
|
|
137
200
|
raise VersionTypeError("Version must be an integer.")
|
|
@@ -139,3 +202,21 @@ def _validate_version(version: int, max_version: int) -> None:
|
|
|
139
202
|
raise InvalidVersionError(
|
|
140
203
|
f"Version {version} is above the maximum allowed version {max_version}."
|
|
141
204
|
)
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def remove_endpoint(
|
|
208
|
+
postfix: str,
|
|
209
|
+
*,
|
|
210
|
+
from_version: int,
|
|
211
|
+
app_name: str | None = None,
|
|
212
|
+
) -> None:
|
|
213
|
+
"""Remove a logical endpoint from a version onward.
|
|
214
|
+
|
|
215
|
+
A later declaration with a higher source version can reintroduce it.
|
|
216
|
+
"""
|
|
217
|
+
if not isinstance(postfix, str):
|
|
218
|
+
raise TypeError("postfix must be a string.")
|
|
219
|
+
if postfix.startswith("/"):
|
|
220
|
+
raise VersioningError("postfix must be relative and must not start with '/'.")
|
|
221
|
+
app_name_part = f"{app_name}/" if app_name else ""
|
|
222
|
+
registry.remove(f"{app_name_part}{postfix}", from_version)
|