API Demo - Django

A Python-based RESTful API built with Django showcasing modern Python development practices and CRUD operations for user management.

🎯 Project Overview

This project is part of a multi-language series demonstrating equivalent server implementations across different technologies. This Django version showcases:

• Django framework with Django REST Framework
• RESTful API design patterns
• Input validation with Django serializers
• Comprehensive testing with Django's testing framework
• Docker containerization
• Modern Python development practices
• Clean architecture with Django's MVC pattern

🛠 Tech Stack

• Runtime: Python 3.8+
• Framework: Django 5.2.5
• Database: SQLite (default)
• Validation: Django serializers
• Testing: pytest with Django integration and comprehensive test coverage
• Package Management: pip with requirements.txt and pyproject.toml
• Code Quality: pylint with 10/10 rating across all modules
• Containerization: Docker & Docker Compose

🚀 Quick Start

Prerequisites

• Python 3.8+ and pip
• OR Docker and Docker Compose

Option 1: Local Development

1. Clone and navigate to the project

   git clone <repository-url>
   cd api-demo-django

2. Create and activate virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Run database migrations

   python manage.py migrate

5. Start the development server

   python manage.py runserver

6. Server is now running at http://localhost:8000

Option 2: Docker (Recommended for Testing)

1. Prerequisites

   • Docker Desktop installed and running
   • Docker Compose (included with Docker Desktop)

2. Clone and navigate to the project

   git clone <repository-url>
   cd api-demo-django

3. Start with Docker Compose

   docker-compose up --build

4. Access the application

   • API Server: http://localhost:8000
   • Users API: http://localhost:8000/users
   • Admin Interface: http://localhost:8000/admin/ (admin/admin)

5. What happens automatically

   • ✅ Container builds with Python 3.11 and dependencies
   • ✅ Database migrations run automatically
   • ✅ User store seeded with 10 sample users
   • ✅ Admin superuser created (username: admin, password: admin)
   • ✅ Development server starts with hot reloading

6. Stop the container when done

   docker-compose down

📋 API Endpoints

The API provides the following endpoints for user management:

Base URL

http://localhost:8000

Endpoints

Method	Endpoint	Description	Body Required
GET	/	Homepage	No
GET	/users	Get all users	No
POST	/user	Create a new user	Yes
GET	/user/:id	Get user by ID	No
PATCH	/user/:id	Update user by ID	Yes
DELETE	/user/:id	Delete user by ID	No

User Data Structure

{
	"id": "string (UUID)",
	"firstName": "string",
	"lastName": "string",
	"email": "string",
	"phone": "string",
	"createdAt": "string (ISO date)",
	"updatedAt": "string (ISO date)"
}

🧪 Testing the API

Using curl

1. Get all users:

curl http://localhost:8000/users

2. Get a specific user:

curl http://localhost:8000/user/1

3. Create a new user:

curl -X POST http://localhost:8000/user \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-555-1234"
  }'

4. Update a user:

curl -X PATCH http://localhost:8000/user/1 \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "email": "jane.doe@example.com"
  }'

5. Delete a user:

curl -X DELETE http://localhost:8000/user/1

Using a GUI Tool (Postman, Insomnia, etc.)

Import the following collection or manually create requests:

• Base URL: http://localhost:8000
• Set Content-Type: application/json for POST/PATCH requests
• Use the endpoints listed above

🏗 Project Structure

api-demo-django/
├── config/                   # Django project configuration
│   ├── __init__.py
│   ├── settings.py           # Django settings
│   ├── urls.py               # Main URL configuration
│   ├── wsgi.py               # WSGI configuration
│   └── asgi.py               # ASGI configuration
├── users/                    # Django app for user operations
│   ├── __init__.py           # Python package marker
│   ├── admin.py              # Django admin configuration with User model
│   ├── apps.py               # App configuration with auto-seeding
│   ├── migrations/           # Database migration files
│   │   └── __init__.py
│   ├── models.py             # User data models with comprehensive docstrings
│   ├── serializers.py        # DRF serializers for validation and data transformation
│   ├── store.py              # In-memory data store with CRUD operations
│   ├── tests/                # Comprehensive test suite
│   │   ├── test_serializers.py  # Unit tests for serializers
│   │   └── test_users_api.py    # API integration tests
│   ├── urls.py               # App-specific URL patterns
│   └── views.py              # API views using Django REST Framework
├── manage.py                 # Django management script
├── requirements.txt          # Python dependencies
├── pyproject.toml            # pytest configuration and project metadata
├── conftest.py               # pytest fixtures and test configuration
├── Dockerfile               # Docker image definition
├── docker-compose.yml       # Development Docker setup
├── docker-compose.prod.yml  # Production Docker setup
├── entrypoint.sh            # Container initialization script
├── .dockerignore            # Docker build context exclusions
└── DOCKER_README.md         # Detailed Docker documentation

📱 Users App Implementation

The users/ directory contains a complete Django app that implements user management functionality:

Key Components

📄 store.py: In-memory data store

• Contains all CRUD operations for user management
• Pre-seeded with 10 sample users for testing
• Uses Python dictionaries to simulate database records
• Implements UUID-based user identification
• Provides functions: list_users(), get_user(), create_user(), update_user(), delete_user()

🔍 serializers.py: Data validation and transformation

• UserCreateSerializer: Validates required fields for new users (firstName, email)
• UserUpdateSerializer: Validates optional fields for user updates
• Uses Django REST Framework serializers for automatic validation
• Handles email validation and field length constraints

🎯 views.py: API endpoints implementation

• UsersListView: GET /users - Returns all users
• UserCreateView: POST /user - Creates a new user
• UserDetailView: GET/PATCH/DELETE /user/<id> - User-specific operations
• Uses Django REST Framework's APIView for clean request/response handling
• Implements proper HTTP status codes (200, 201, 404, 204)

🛣️ urls.py: URL routing configuration

• Maps HTTP endpoints to view classes
• Supports UUID-based user identification in URLs
• Clean RESTful URL patterns

🧪 tests/: Comprehensive test suite

• test_serializers.py: Unit tests for UserCreateSerializer and UserUpdateSerializer
• test_users_api.py: Integration tests for all API endpoints
• Uses pytest with Django integration for modern testing practices
• Includes API client fixtures and test markers for organization

Data Flow

1. Request → Django URL dispatcher (urls.py)
2. Routing → Appropriate view class (views.py)
3. Validation → DRF serializers (serializers.py)
4. Processing → In-memory store operations (store.py)
5. Response → JSON data with proper HTTP status codes

🧪 Running Tests

This project uses pytest with Django integration for comprehensive testing.

Run all tests:

pytest

Run tests with verbose output:

pytest -v

Run specific test files:

pytest users/tests/test_serializers.py
pytest users/tests/test_users_api.py

Run tests with markers:

pytest -m api    # Run only API integration tests
pytest -m unit   # Run only unit tests

Run tests with coverage report:

pip install pytest-cov
pytest --cov=users --cov-report=html

🔧 Development Scripts

python manage.py runserver        # Start development server
python manage.py migrate          # Apply database migrations
python manage.py makemigrations   # Create new migrations
pytest                            # Run tests (recommended)
python manage.py test             # Run tests (Django native)
python manage.py shell            # Open Django shell
python manage.py createsuperuser  # Create admin user
python manage.py collectstatic    # Collect static files
pylint users/                     # Check code quality

🐳 Docker Commands

Basic Commands

docker-compose up --build   # Build and start container (recommended)
docker-compose up           # Start container (if already built)
docker-compose up -d        # Start container in detached mode
docker-compose down         # Stop and remove container
docker-compose logs web     # View container logs
docker-compose ps           # Show running containers

Development Commands

# Run Django management commands in container
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py createsuperuser
docker-compose exec web python manage.py shell
docker-compose exec web python manage.py test

# Access container shell
docker-compose exec web bash

# User store operations
docker-compose exec web python manage.py shell -c "
from users.store import reset_and_seed
reset_and_seed()
print('User store reset and reseeded')
"

Production Commands

# Use production configuration
docker-compose -f docker-compose.prod.yml up --build

# Build without cache
docker-compose build --no-cache

Troubleshooting

# Clean restart
docker-compose down
docker-compose build --no-cache
docker-compose up

# Check if Docker daemon is running
docker info

# Start Docker Desktop (macOS)
open -a Docker

🐳 Docker Architecture

This project includes a complete Docker setup optimized for both development and production:

Container Features

• Base Image: Python 3.11 slim for smaller image size
• Non-root User: Security-focused container with dedicated app user
• Hot Reloading: Volume mounting for live code changes in development
• Auto-initialization: Automatic database setup and user store seeding
• Health Checks: Built-in Django development server monitoring

Development vs Production

• Development (docker-compose.yml): Volume mounting, debug mode, hot reloading
• Production (docker-compose.prod.yml): Gunicorn WSGI server, optimized settings

Automatic Setup

The entrypoint.sh script automatically handles:

1. 🔄 Database migrations for Django admin functionality
2. 🌱 User store seeding with 10 sample users
3. 👤 Admin superuser creation (admin/admin)
4. 🚀 Application startup

File Structure

Docker Configuration/
├── Dockerfile               # Multi-stage build optimized for Python
├── docker-compose.yml       # Development with volume mounting
├── docker-compose.prod.yml  # Production with Gunicorn
├── entrypoint.sh           # Initialization and setup script
├── .dockerignore           # Build context optimization
└── DOCKER_README.md        # Comprehensive Docker documentation

For detailed Docker documentation, see DOCKER_README.md.

✨ Features Demonstrated

• RESTful API Design: Proper HTTP methods and status codes
• Input Validation: Django REST Framework serializers for request validation
• Error Handling: DRF exception handling with proper HTTP status codes
• Type Safety: Python type hints throughout the codebase
• Modern Testing: pytest with Django integration, fixtures, and test markers
• Code Quality: 10/10 pylint rating across all modules with comprehensive docstrings
• Test Coverage: Unit tests for serializers and integration tests for API endpoints
• Containerization: Complete Docker setup with development and production configurations
• In-Memory Storage: Custom store module for demonstration purposes
• Separation of Concerns: Clean Django architecture with views, serializers, and data layer
• Documentation: Comprehensive docstrings following Python standards

💾 Data Storage

This demo uses in-memory storage implemented in users/store.py for simplicity. Key features:

• No Database Required: Uses Python lists and dictionaries to store data
• Pre-seeded Data: Automatically loads 10 sample users on first access
• Session Persistence: Data persists during the application session
• Reset on Restart: All data resets when the server restarts
• UUID Identification: Each user has a unique UUID identifier
• Realistic Data: Sample users include realistic names, emails, and phone numbers

The store module provides a clean interface that could easily be replaced with a database backend in a production environment.

🔄 Sample Data

The API comes with 10 pre-loaded users for testing. You can immediately test GET requests without needing to create data first.

🏆 Code Quality

This project maintains high code quality standards:

• Pylint Score: 10.00/10 across all modules
• Documentation: Comprehensive docstrings for all classes, methods, and functions
• Type Hints: Full type annotation coverage for better IDE support and code clarity
• Testing: 100% test coverage for serializers and API endpoints
• Standards: Follows PEP 8 and Django best practices

📝 Notes for Reviewers

• No Database: Uses in-memory storage for demo simplicity
• Environment: Configured for development with Django's debug mode
• Validation: All inputs are validated using Django REST Framework serializers
• Error Handling: Proper HTTP status codes and error responses using DRF
• Testing: Modern pytest setup with Django integration and comprehensive test coverage
• Code Style: Follows Python and Django best practices with perfect linting scores
• Architecture: Uses Django's app-based architecture with clear separation of concerns
• Documentation: Every module, class, and function includes detailed docstrings

---