Poll Management API

Overview

RESTful API built with FastAPI for creating polls, managing choices, and collecting votes with real-time result aggregation. Features async database operations, comprehensive error handling, and full CRUD functionality.

Features

• Poll Management: Create, read, update, delete polls with timestamps
• Choice Management: Full CRUD operations for poll choices
• Voting System: Cast votes with optional voter information
• Results Aggregation: Real-time vote counting and result summaries
• Data Validation: Request/response validation with Pydantic models
• Error Handling: Consistent HTTP status codes and user-friendly error messages

Tech Stack

• Backend: FastAPI, Python 3.10+
• Database: PostgreSQL with async SQLAlchemy
• Testing: pytest with async support and comprehensive test coverage
• Containerization: Docker & docker-compose for easy deployment
• Data Validation: Pydantic models for type safety

API Endpoints

Polls

Method	Endpoint	Description
GET	/polls/	List all polls
POST	/polls/	Create new poll
GET	/polls/{poll_id}	Get specific poll
PUT	/polls/{poll_id}	Update poll
DELETE	/polls/{poll_id}	Delete poll

Choices

Method	Endpoint	Description
POST	/polls/{poll_id}/choices/	Add choice to poll
GET	/polls/{poll_id}/choices/	List poll choices
GET	/polls/{poll_id}/choices/{choice_id}	Get specific choice
PUT	/polls/{poll_id}/choices/{choice_id}	Update choice
DELETE	/polls/{poll_id}/choices/{choice_id}	Delete choice

Voting & Results

Method	Endpoint	Description
POST	/polls/{poll_id}/choices/{choice_id}/vote	Cast vote
GET	/polls/{poll_id}/results	Get poll results

Quick Start

Prerequisites

• Python 3.10+
• Docker & Docker Compose

Installation & Setup

1. Clone repository

   git clone https://github.com/NightSoma/poll-management-api
   cd poll-management-api

2. Start with Docker (Recommended)

   docker-compose up --build

   API will be available at http://localhost:8000

3. Local Development Setup

   # Install dependencies
   pip install -r requirements.txt
   
   # Run tests
   pytest
   
   # Start development server (requires database setup)
   uvicorn app.main:app --reload

Usage Examples

Create a Poll

curl -X POST "http://localhost:8000/polls/" \
     -H "Content-Type: application/json" \
     -d '{"question_text": "What is your favorite programming language?"}'

Add Choices

curl -X POST "http://localhost:8000/polls/1/choices/" \
     -H "Content-Type: application/json" \
     -d '{"choice_text": "Python"}'

Cast Vote

curl -X POST "http://localhost:8000/polls/1/choices/1/vote" \
     -H "Content-Type: application/json" \
     -d '{"voter_info": "Anonymous User"}'

Get Results

curl "http://localhost:8000/polls/1/results"

Interactive Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=app

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

Database Schema

polls (id, question_text, pub_date)
  ↓
choices (id, poll_id, choice_text)
  ↓  
votes (id, choice_id, voted_at, voter_info)

Development Tools

• Code Formatting: Ruff
• Type Checking: FastAPI + Pydantic
• Testing Framework: pytest with async support
• API Documentation: Auto-generated with FastAPI

License

MIT License - see LICENSE file for details.

Contact

[Roman Kuryliak] - [romahakl@gmail.com]

Project Link: https://github.com/NightSoma/poll-management-api