Python Address Book API

A Python FastAPI microservice for managing user address directory with full CRUD operations and search functionality.

Features

• ✅ Create, Read, Update, Delete user addresses
• ✅ Search addresses by name, phone, email, city, or keyword
• ✅ RESTful API with JSON responses
• ✅ In-memory database (thread-safe)
• ✅ Health check endpoints via /actuator
• ✅ Auto-generated Swagger/OpenAPI documentation
• ✅ Comprehensive test coverage (80%+)
• ✅ Docker containerization
• ✅ Helm chart for Kubernetes deployment
• ✅ GitHub Actions CI/CD pipeline

Tech Stack

• Python 3.11+
• FastAPI (web framework)
• Pydantic (data validation)
• Uvicorn (ASGI server)
• pytest (testing)

Quick Start

Prerequisites

• Python 3.11+

Install and Run

# Clone the repository
cd python-addressbook-api

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run the application
uvicorn main:app --host 0.0.0.0 --port 8080 --reload

The application will start at http://localhost:8080

Using Make

# Install dependencies
make install

# Run the application
make run

# Run tests
make test

# Run tests with coverage
make coverage

# Check coverage threshold (80%)
make coverage-check

Using Docker

# Build Docker image
docker build -t addressbook-api .

# Run container
docker run -p 8080:8080 addressbook-api

Swagger UI

Access the interactive API documentation at:

• Swagger UI: http://localhost:8080/swagger
• ReDoc: http://localhost:8080/redoc
• OpenAPI JSON: http://localhost:8080/swagger/doc.json

API Endpoints

Method	Endpoint	Description
POST	/api/addresses	Create a new address
GET	/api/addresses	Get all addresses
GET	/api/addresses/{id}	Get address by ID
PUT	/api/addresses/{id}	Update address
DELETE	/api/addresses/{id}	Delete address
GET	/api/addresses/search?q={keyword}	Search addresses
GET	/api/addresses/search/name?name={name}	Search by name
GET	/api/addresses/search/city?city={city}	Search by city

API Usage Examples (curl)

Create a new address

curl -X POST http://localhost:8080/api/addresses \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "1234567890",
    "email": "john@example.com",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip_code": "10001",
    "country": "USA"
  }'

Get all addresses

curl http://localhost:8080/api/addresses

Get address by ID

curl http://localhost:8080/api/addresses/1

Update an address

curl -X PUT http://localhost:8080/api/addresses/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "john.smith@example.com",
    "city": "Los Angeles"
  }'

Delete an address

curl -X DELETE http://localhost:8080/api/addresses/1

Search addresses

curl "http://localhost:8080/api/addresses/search?q=John"
curl "http://localhost:8080/api/addresses/search/name?name=John"
curl "http://localhost:8080/api/addresses/search/city?city=New%20York"

Check health status

curl http://localhost:8080/actuator/health

Testing

# Run all tests
pytest -v

# Run tests with coverage
pytest --cov=app --cov-report=term-missing --cov-report=html

# Run specific test file
pytest tests/test_api.py -v

Project Structure

python-addressbook-api/
├── main.py                 # Application entry point
├── app/
│   ├── __init__.py
│   ├── config.py           # Configuration settings
│   ├── models.py           # Pydantic models
│   ├── repository.py       # In-memory data store
│   ├── service.py          # Business logic
│   └── routers/
│       ├── __init__.py
│       ├── addresses.py    # Address API routes
│       └── health.py       # Health check routes
├── tests/
│   ├── __init__.py
│   ├── test_repository.py  # Repository unit tests
│   ├── test_service.py     # Service unit tests
│   └── test_api.py         # API integration tests
├── helm/
│   └── addressbook/        # Helm chart files
├── .github/
│   └── workflows/
│       └── ci-cd.yml       # GitHub Actions workflow
├── Dockerfile
├── Makefile
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
└── README.md

Deployment

GitHub Actions

The CI/CD pipeline automatically:

1. Runs tests with coverage
2. Builds and pushes Docker image to GitHub Container Registry
3. Runs security scan (Bandit)
4. Deploys to Kubernetes (configurable)

Kubernetes (Helm)

# Install
helm install addressbook ./helm/addressbook

# Upgrade
helm upgrade addressbook ./helm/addressbook

# Uninstall
helm uninstall addressbook

Configuration

Environment variables:

Variable	Description	Default
SERVER_PORT	Application port	8080
SERVER_HOST	Server host binding	0.0.0.0

License

Apache 2.0