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.
Files changed (58) hide show
  1. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/CHANGELOG.md +58 -1
  2. {django_api_versioning-1.0.1/django_api_versioning.egg-info → django_api_versioning-1.2.0}/PKG-INFO +58 -11
  3. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/README.md +56 -9
  4. django_api_versioning-1.2.0/django_api_versioning/__init__.py +10 -0
  5. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/decorators.py +81 -0
  6. django_api_versioning-1.2.0/django_api_versioning/lifecycle.py +283 -0
  7. django_api_versioning-1.2.0/django_api_versioning/lifecycle_metadata.py +62 -0
  8. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/management/commands/check_versions.py +25 -3
  9. django_api_versioning-1.2.0/django_api_versioning/management/commands/migrate_endpoints.py +433 -0
  10. django_api_versioning-1.2.0/django_api_versioning/registry.py +684 -0
  11. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/reverse.py +15 -8
  12. django_api_versioning-1.2.0/django_api_versioning/routers.py +433 -0
  13. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/settings.py +44 -3
  14. django_api_versioning-1.2.0/django_api_versioning/spectacular.py +75 -0
  15. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/testing.py +51 -17
  16. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0/django_api_versioning.egg-info}/PKG-INFO +58 -11
  17. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/SOURCES.txt +7 -0
  18. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/requires.txt +1 -1
  19. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/pyproject.toml +2 -2
  20. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/requirements-dev.txt +1 -1
  21. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/conftest.py +2 -2
  22. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_decorators.py +140 -2
  23. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_lifecycle.py +100 -14
  24. django_api_versioning-1.2.0/tests/test_lifecycle_integration.py +560 -0
  25. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_management_commands.py +294 -0
  26. django_api_versioning-1.2.0/tests/test_registry.py +1138 -0
  27. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_reverse.py +46 -1
  28. django_api_versioning-1.2.0/tests/test_route_removal.py +281 -0
  29. django_api_versioning-1.2.0/tests/test_routers.py +491 -0
  30. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_settings.py +76 -1
  31. django_api_versioning-1.2.0/tests/test_spectacular.py +172 -0
  32. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_testing_utils.py +45 -0
  33. django_api_versioning-1.0.1/django_api_versioning/__init__.py +0 -4
  34. django_api_versioning-1.0.1/django_api_versioning/lifecycle.py +0 -197
  35. django_api_versioning-1.0.1/django_api_versioning/management/commands/migrate_endpoints.py +0 -249
  36. django_api_versioning-1.0.1/django_api_versioning/registry.py +0 -195
  37. django_api_versioning-1.0.1/tests/test_registry.py +0 -464
  38. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/LICENSE +0 -0
  39. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/MANIFEST.in +0 -0
  40. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/channels.py +0 -0
  41. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/exceptions.py +0 -0
  42. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/management/__init__.py +0 -0
  43. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/management/commands/__init__.py +0 -0
  44. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/py.typed +0 -0
  45. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning/urls.py +0 -0
  46. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/dependency_links.txt +0 -0
  47. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/django_api_versioning.egg-info/top_level.txt +0 -0
  48. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/pytest.ini +0 -0
  49. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/requirements.txt +0 -0
  50. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/setup.cfg +0 -0
  51. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/__init__.py +0 -0
  52. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/settings.py +0 -0
  53. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_channels.py +0 -0
  54. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_channels_extra.py +0 -0
  55. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_distribution_contents.py +0 -0
  56. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_exceptions.py +0 -0
  57. {django_api_versioning-1.0.1 → django_api_versioning-1.2.0}/tests/test_segment_model.py +0 -0
  58. {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
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: django-api-versioning
3
- Version: 1.0.1
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.1; python_version < "3.11" and extra == "dev"
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 test it with `assert_version_matrix()`.
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 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**.
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
- 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`.
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 is optional. The package also supports Django function-based and class-based views. For a Django-only project, install just:
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 ViewSet boundary
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
- 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.
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
- See [ViewSet support and limitations](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/).
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
- 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.
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 test it with `assert_version_matrix()`.
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 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**.
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
- 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`.
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 is optional. The package also supports Django function-based and class-based views. For a Django-only project, install just:
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 ViewSet boundary
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
- 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.
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
- See [ViewSet support and limitations](https://mojtaba-arvin.github.io/django-api-versioning/articles/025-django-api-versioning-viewset-support-limitations/).
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
- 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.
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
 
@@ -0,0 +1,10 @@
1
+ from .decorators import endpoint, remove_endpoint, set_endpoint_lifecycle, ver_range
2
+ from .reverse import api_reverse
3
+
4
+ __all__ = [
5
+ "endpoint",
6
+ "remove_endpoint",
7
+ "set_endpoint_lifecycle",
8
+ "ver_range",
9
+ "api_reverse",
10
+ ]
@@ -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)