Skip to content

Commit aeb9175

Browse files
committed
Update setup.py with new description and version
1 parent f8fd960 commit aeb9175

File tree

2 files changed

+18
-15
lines changed

2 files changed

+18
-15
lines changed

README.md

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
1-
21
# Django API Versioning
32

43
[![PyPI version](https://badge.fury.io/py/django-api-versioning.svg)](https://badge.fury.io/py/django-api-versioning)
54
[![Build Status](https://github.com/mojtaba-arvin/django-api-versioning/actions/workflows/tests.yml/badge.svg)](https://github.com/mojtaba-arvin/django-api-versioning/actions)
65
[![codecov](https://codecov.io/gh/mojtaba-arvin/django-api-versioning/branch/main/graph/badge.svg)](https://codecov.io/gh/mojtaba-arvin/django-api-versioning)
76
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
87

9-
**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.
109

1110
## Features
1211

@@ -19,7 +18,7 @@
1918

2019
## Installation
2120

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:
2322

2423
```bash
2524
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
7372

7473
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.
7574

76-
7775
#### Example for Function-Based Views (FBVs):
7876

7977
```python
@@ -88,6 +86,7 @@ def users_view(request):
8886
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`.
8987

9088
#### Example for Class-Based Views (CBVs):
89+
9190
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:
9291

9392
```python
@@ -108,7 +107,6 @@ class UsersView(View):
108107

109108
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:
110109

111-
112110
```python
113111
from rest_framework.views import APIView
114112
from rest_framework.response import Response
@@ -122,25 +120,26 @@ class UsersAPIView(APIView):
122120
```
123121

124122
#### URL Generation Based on Versioning:
123+
125124
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:
126125

127-
* `/api/v1/account_app/users`
128-
* `/api/v2/account_app/users`
126+
- `/api/v1/account_app/users`
127+
- `/api/v2/account_app/users`
129128

130129
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.
131130

132131
#### Additional Configuration Options:
133132

134133
**Without `app_name`:** If you don't pass `app_name` in the decorator, like this:
134+
135135
```python
136136
@endpoint("users", version=2, view_name="users_list_api")
137137
```
138138

139139
The generated URLs will be:
140140

141-
* `/api/v1/users`
142-
* `/api/v2/users`
143-
141+
- `/api/v1/users`
142+
- `/api/v2/users`
144143

145144
**Without `version`:** If you don't pass `version` in the decorator, like this:
146145

@@ -150,7 +149,7 @@ The generated URLs will be:
150149

151150
API versioning will be disabled (`API_BASE_PATH` as prefix will be removed) for that view. The only URL generated will be:
152151

153-
* `/users`
152+
- `/users`
154153

155154
**Setting `backward=False`:** By default, the `backward` parameter is set to `True`, which ensures backward compatibility. If you explicitly set `backward=False`, like this:
156155

@@ -160,7 +159,7 @@ API versioning will be disabled (`API_BASE_PATH` as prefix will be removed) for
160159

161160
The generated URL will be only version 2:
162161

163-
* `api/v2/users`
162+
- `api/v2/users`
164163

165164
4. Run the Server:
166165

@@ -169,16 +168,21 @@ python manage.py runserver
169168
```
170169

171170
## Notes
171+
172172
### 1. `API_BASE_PATH` in settings Must Include ‍‍`{version}`:
173+
173174
The `API_BASE_PATH` should always include `{version}` to ensure proper API versioning. This is important for correctly mapping API routes to different versions.
174175

175176
### 2. Using `app_name` in the `endpoint` decorator:
177+
176178
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.
177179

178180
### 3. Views with Version Less Than `API_MIN_VERSION` Are Automatically Ignored:
181+
179182
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.
180183

181184
### 4. URLs for Versions Between `API_MIN_VERSION` <= `version` <= `API_MAX_VERSION`:
185+
182186
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.
183187

184188
### `endpoint` Decorator Function Definition
@@ -199,7 +203,7 @@ def endpoint(
199203
- Uses `API_MIN_VERSION` and `API_MAX_VERSION` from Django settings.
200204
- Supports backward compatibility by registering multiple versions if needed.
201205
- Ensures that no version lower than `API_MIN_VERSION` is registered.
202-
206+
203207
Args:
204208
postfix (str): The endpoint suffix (e.g., "users" → "api/v1/users").
205209
version (Optional[int]): The version of the API. Defaults to None (unversioned).
@@ -216,7 +220,6 @@ def endpoint(
216220
"""
217221
```
218222

219-
220223
## Contributing
221224

222225
Feel free to open an issue or submit a pull request with any improvements or bug fixes. We appreciate contributions to enhance this package!

setup.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
setup(
77
name="django-api-versioning",
8-
version="0.1.0",
8+
version="0.1.1",
99
author="Mojtaba Arvin",
1010
author_email="ArvinDevDay@gmail.com",
1111
description= (

0 commit comments

Comments
 (0)