Other versions: Clique aqui para Português
About • Features • Application Architecture • API Endpoints • Usage Examples • Setup • Author • License
This project is a personal learning exercise focused on building a Django REST API while applying best practices like pagination, filtering, searching, and OAuth authentication.
The API allows users to manage tasks, including:
- Creating, updating, retrieving, and deleting tasks.
- Filtering tasks by priority, status, and deadline.
- Searching tasks by title or description.
- Authenticating users using OAuth2 token-based authentication.
Additionally, a helper script (helper_functions.py, inside the script_examples directory) provides examples of API interactions via Python, demonstrating how to make authenticated requests for querying and managing tasks programmatically.
- OAuth2 authentication: Secure access to the API using token-based authentication.
- Task management endpoints: Supports full CRUD operations (Create, Read, Update, Delete).
- Filtering & Searching: Query tasks based on priority, status, deadline, and text search.
- Pagination: Ensures efficient handling of large datasets.
The Task Manager API is built using Django and Django REST framework. The application follows a modular architecture with the following main components:
- Models: Define the structure of the database tables. The main model is the
Taskmodel, which includes fields for title, description, priority, deadline, status, and user association. - Serializers: Convert model instances to JSON format and validate incoming data.
- Views: Handle the business logic and interact with the models and serializers. The main views include task creation, retrieval, update, and deletion, as well as user registration.
- URLs: Route incoming HTTP requests to the appropriate views.
- Authentication: Uses OAuth2 for secure authentication and authorization.
- User Registration: Users can register by providing a username and password.
- Authentication: Users obtain an access token by providing their credentials.
- Task Management: Authenticated users can create, read, update, and delete tasks.
This is the list of the API routes and the expected JSONs.
| Route | Description |
|---|---|
| POST /register/ | register users (username and password) details |
| POST /o/token/ | requests an access token for a user details |
| POST /api/tasks/ | creates a new task for a user details |
| GET /api/tasks/ | gets all the tasks from a user details |
| GET /api/tasks/?param=value | filters tasks with a specific parameter from a user details |
| GET /api/tasks/{id}/ | gets a task with a specific id from a specific user details |
| PUT /api/tasks/{id}/ | updates a task with a specific id from a specific user details |
| DELETE /api/tasks/{id}/ | deletes a task with a specific id from a specific user details |
REQUEST:
Data
{
"username": "desired-username-here",
"password": "desired-password-here"
}RESPONSE (201):
{"message": "User created successfully"}REQUEST:
Data
{
"grant_type": "password",
"username": "your-username-here",
"password": "your-password-here",
"client_id": "your-client-id-here",
"client_secret": "your-client-secret-here"
}RESPONSE (201):
{
"access_token": "9Lcvhiy108thwJzjTSdyisWMv06XsM",
"expires_in": 36000,
"token_type": "Bearer",
"scope": "read write",
"refresh_token": "QY8MHHiNaK7JzsXqzuo5YKt3dBckjI"
}REQUEST:
Headers
{
"Authorization": "Bearer your-access-token-here"
}Data
{
"title": "New Task",
"description": "This is another task",
"priority": "Low",
"deadline": "2021-12-31",
"status": "Pending",
}RESPONSE (200):
{
"id": 2,
"title": "New Task",
"description": "This is another task",
"priority": "Low",
"deadline": "2021-12-31",
"status": "Pending",
"created_at": "2025-02-15T11:49:44.762223Z",
"updated_at": "2025-02-15T11:49:44.762251Z",
"user": 4
}REQUEST:
Headers
{
"Authorization": "Bearer your-access-token-here"
}RESPONSE (200):
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"title": "New Task",
"description": "This is a new task",
"priority": "Low",
"deadline": "2021-12-31",
"status": "Pending",
"created_at": "2025-02-15T11:44:35.155255Z",
"updated_at": "2025-02-15T11:44:35.155284Z",
"user": 2
},
{
"id": 2,
"title": "New Task",
"description": "This is another task",
"priority": "Low",
"deadline": "2021-12-31",
"status": "Pending",
"created_at": "2025-02-15T11:49:44.762223Z",
"updated_at": "2025-02-15T11:49:44.762251Z",
"user": 2
},
{
"id": 3,
"title": "New Task",
"description": "This is another new task",
"priority": "High",
"deadline": "2021-12-31",
"status": "Pending",
"created_at": "2025-02-16T11:17:00.685599Z",
"updated_at": "2025-02-16T11:17:00.685657Z",
"user": 2
}
]
}REQUEST:
Headers
{
"Authorization": "Bearer your-access-token-here"
}Query Parameters
| Parameter | Type | Description |
|---|---|---|
| search | str | Search for tasks by title or description |
| priority | str | Filter by priority (Low, Medium, High) |
| status | str | Filter by status (Pending, Completed) |
| deadline | date | Filter tasks by deadline (YYYY-MM-DD format) |
Request URL examples:
RESPONSE (200):
Same response pattern shown in GET
REQUEST:
Same request pattern as GET
RESPONSE(200):
Same response pattern shown in POST
REQUEST:
Same request pattern as POST
RESPONSE (200):
Same response pattern shown in POST
REQUEST:
Same request pattern as GET
RESPONSE (204):
There is no content in the response.
If you need more practical examples of how to interact with the API using Python scripts, please check the following files inside the script_examples directory:
helper_functions.py – Contains functions for performing CRUD operations on tasks.
example_add_task.py – Demonstrates how to add tasks using helper_functions.py.
example_register.py – Shows how to register a new user via the API.
These scripts illustrate how to automate and integrate the Task Manager API into other applications.
To run the project locally:
# Clone the repository
git clone https://github.com/rafaelmeller/django-task-manager.git
# Navigate to project folder
cd django-task-manager
# Create a virtual environment
python3 -m venv .venv
# Activate virtual environment
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Apply database migrations to create necessary tables
python manage.py migrate
# (Optional) Create a superuser to access the Django admin panel
python manage.py createsuperuser
# Run the development server
python manage.py runserverThis project was designed and developed by Rafael Meller.
This project is licensed under the MIT license.