Employee Management API

A RESTful API built with FastAPI for managing employee data with full CRUD operations, filtering capabilities, and soft delete functionality.

Features

• Create, Read, Update, and Delete employee records
• Soft delete (mark as inactive) and hard delete options
• Filter employees by department and active status
• Pagination support
• Email validation
• PostgreSQL database with SQLAlchemy ORM
• Docker containerization
• Interactive API documentation (Swagger UI & ReDoc)

Tech Stack

• Framework: FastAPI 0.121.2
• Database: PostgreSQL 15
• ORM: SQLAlchemy 2.0.44
• Migration: Alembic 1.17.2
• Container: Docker & Docker Compose
• Python: 3.13+

Project Structure

employee-api/
  app/
      __init__.py
        main.py          # FastAPI app & endpoints
        models.py        # SQLAlchemy models
        schemas.py       # Pydantic schemas
        crud.py          # Database operations
        database.py      # Database configuration
  docker-compose.yml
  Dockerfile
  pyproject.toml
  .env
  README.md

Quick Start

Using Docker (Recommended)

1. Clone the repository and navigate to the project directory
2. Start the services:

docker-compose up --build

3. Access the API
   • API: http://localhost:8000
   • Swagger UI: http://localhost:8000/docs
   • ReDoc: http://localhost:8000/redoc

Local Development

1. Install dependencies with uv:

uv sync

2. Set up environment variables in .env:

DATABASE_URL=postgresql://employee_user:employee_pass@localhost:5432/employee_db
POSTGRES_USER=employee_user
POSTGRES_PASSWORD=employee_pass
POSTGRES_DB=employee_db

3. Start PostgreSQL (if using Docker):

docker-compose up db

4. Run the application:

uv run uvicorn app.main:app --reload

API Endpoints

Employee Operations

Method	Endpoint	Description
POST	/employees/	Create a new employee
GET	/employees/	Get all employees (with filters)
GET	/employees/{id}	Get employee by ID
PUT	/employees/{id}	Update employee
DELETE	/employees/{id}	Soft delete employee
DELETE	/employees/{id}/permanent	Permanently delete employee

Other Endpoints

Method	Endpoint	Description
GET	/	Welcome message
GET	/health	Health check
GET	/docs	Swagger UI documentation
GET	/redoc	ReDoc documentation

Employee Schema

{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "department": "string",
  "position": "string",
  "salary": 0.0,
  "is_active": true
}

Query Parameters

GET /employees/

• skip: Number of records to skip (default: 0)
• limit: Maximum records to return (default: 100, max: 100)
• department: Filter by department name
• is_active: Filter by active status (true/false)

Example:

GET /employees/?department=Engineering&is_active=true&skip=0&limit=10

Example Usage

Create an Employee

curl -X POST "http://localhost:8000/employees/" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@company.com",
    "department": "Engineering",
    "position": "Senior Developer",
    "salary": 95000.00,
    "is_active": true
  }'

Get All Employees

curl "http://localhost:8000/employees/"

Filter by Department

curl "http://localhost:8000/employees/?department=Engineering"

Update an Employee

curl -X PUT "http://localhost:8000/employees/1" \
  -H "Content-Type: application/json" \
  -d '{
    "salary": 105000.00,
    "position": "Lead Developer"
  }'

Soft Delete an Employee

curl -X DELETE "http://localhost:8000/employees/1"

Database Migrations

Using Alembic for database migrations:

# Create a new migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head

# Rollback migration
uv run alembic downgrade -1

Environment Variables

• DATABASE_URL: PostgreSQL connection string
• POSTGRES_USER: Database user
• POSTGRES_PASSWORD: Database password
• POSTGRES_DB: Database name

Docker Commands

# Start all services
docker-compose up

# Start in detached mode
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f

# Rebuild containers
docker-compose up --build

Development

Install development dependencies:

uv sync

Run the development server with auto-reload:

uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000