You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Django API Versioning** is a powerful and flexible library for managing API versioning in Django projects. It allows you to easily define and manage different versions of your API endpoints using decorators, ensuring backward compatibility and clean code organization.
8
+
**Django API Versioning** is a powerful and flexible library for managing [API versioning in Django](https://github.com/mojtaba-arvin/django-api-versioning) projects. It allows you to easily define and manage different versions of your API endpoints using decorators, ensuring backward compatibility and clean code organization.
10
9
11
10
## Features
12
11
@@ -19,7 +18,7 @@
19
18
20
19
## Installation
21
20
22
-
You can install Django API Versioning via pip:
21
+
You can [install Django API Versioning](https://pypi.org/project/django-api-versioning/) via pip:
23
22
24
23
```bash
25
24
pip install django-api-versioning
@@ -73,7 +72,6 @@ or you have already have a `ROOT_URLCONF` in settings, you only need to import t
73
72
74
73
The `endpoint` decorator can be used in both function-based views (FBVs) and class-based views (CBVs). It's also fully compatible with `Django Rest Framework (DRF)`. The decorator allows you to define versioning for your API views and supports backward compatibility by default and you don't need to pass `backward=True` flag to the `endpoint` decorator.
75
74
76
-
77
75
#### Example for Function-Based Views (FBVs):
78
76
79
77
```python
@@ -88,6 +86,7 @@ def users_view(request):
88
86
In this example, the `users_view` function is decorated with the endpoint decorator. This specifies that the view is accessible under version `2` of the API and **supports backward compatibility**. The `backward=True` flag as default ensures that users can also access the previous version (version `1`) at `/api/v1/account_app/users`.
89
87
90
88
#### Example for Class-Based Views (CBVs):
89
+
91
90
For class-based views, you can apply the decorator to methods such as `get`, `post`, or any other HTTP method you need to handle. Here’s an example:
92
91
93
92
```python
@@ -108,7 +107,6 @@ class UsersView(View):
108
107
109
108
If you have already installed [Django Rest Framework](https://www.django-rest-framework.org/#installation), the `endpoint` decorator can be easily applied to APIView or viewsets. Here’s an example with a DRF APIView:
110
109
111
-
112
110
```python
113
111
from rest_framework.views import APIView
114
112
from rest_framework.response import Response
@@ -122,25 +120,26 @@ class UsersAPIView(APIView):
122
120
```
123
121
124
122
#### URL Generation Based on Versioning:
123
+
125
124
Once the decorator is applied, the URLs for your API will be generated based on the version specified in the decorator. For example, if the `API_MIN_VERSION` in your settings.py is set to `1` and the version in the decorator is set to `2`, the following URLs will be available:
126
125
127
-
*`/api/v1/account_app/users`
128
-
*`/api/v2/account_app/users`
126
+
-`/api/v1/account_app/users`
127
+
-`/api/v2/account_app/users`
129
128
130
129
The `API_MIN_VERSION` setting ensures that users can access the API using different versions, providing backward compatibility. You can adjust which versions are considered valid by modifying the `API_MIN_VERSION` and `version` numbers in the decorators.
131
130
132
131
#### Additional Configuration Options:
133
132
134
133
**Without `app_name`:** If you don't pass `app_name` in the decorator, like this:
**Without `version`:** If you don't pass `version` in the decorator, like this:
146
145
@@ -150,7 +149,7 @@ The generated URLs will be:
150
149
151
150
API versioning will be disabled (`API_BASE_PATH` as prefix will be removed) for that view. The only URL generated will be:
152
151
153
-
*`/users`
152
+
-`/users`
154
153
155
154
**Setting `backward=False`:** By default, the `backward` parameter is set to `True`, which ensures backward compatibility. If you explicitly set `backward=False`, like this:
156
155
@@ -160,7 +159,7 @@ API versioning will be disabled (`API_BASE_PATH` as prefix will be removed) for
160
159
161
160
The generated URL will be only version 2:
162
161
163
-
*`api/v2/users`
162
+
-`api/v2/users`
164
163
165
164
4. Run the Server:
166
165
@@ -169,16 +168,21 @@ python manage.py runserver
169
168
```
170
169
171
170
## Notes
171
+
172
172
### 1. `API_BASE_PATH` in settings Must Include `{version}`:
173
+
173
174
The `API_BASE_PATH` should always include `{version}` to ensure proper API versioning. This is important for correctly mapping API routes to different versions.
174
175
175
176
### 2. Using `app_name` in the `endpoint` decorator:
177
+
176
178
It's recommended to fill in the `app_name` in the `endpoint` decorator to make the API URLs **more unique and organized**. This ensures that the routes are scoped under the correct app, avoiding potential conflicts and making them easier to manage.
177
179
178
180
### 3. Views with Version Less Than `API_MIN_VERSION` Are Automatically Ignored:
181
+
179
182
Any view whose `version` is less than the `API_MIN_VERSION` will be automatically ignored. This means clients will no longer have access to these older versions, **without the need to manually edit or remove code**. This is handled automatically by the package.
180
183
181
184
### 4. URLs for Versions Between `API_MIN_VERSION` <= `version` <= `API_MAX_VERSION`:
185
+
182
186
Endpoints that have versions within the range defined by `API_MIN_VERSION` <= `version` <= `API_MAX_VERSION` will always have a corresponding URL generated. This ensures that only valid versions will be accessible, providing flexibility in version management.
183
187
184
188
### `endpoint` Decorator Function Definition
@@ -199,7 +203,7 @@ def endpoint(
199
203
- Uses `API_MIN_VERSION` and `API_MAX_VERSION` from Django settings.
200
204
- Supports backward compatibility by registering multiple versions if needed.
201
205
- Ensures that no version lower than `API_MIN_VERSION` is registered.
202
-
206
+
203
207
Args:
204
208
postfix (str): The endpoint suffix (e.g., "users" → "api/v1/users").
205
209
version (Optional[int]): The version of the API. Defaults to None (unversioned).
@@ -216,7 +220,6 @@ def endpoint(
216
220
"""
217
221
```
218
222
219
-
220
223
## Contributing
221
224
222
225
Feel free to open an issue or submit a pull request with any improvements or bug fixes. We appreciate contributions to enhance this package!
0 commit comments