Poll and Voting API

A comprehensive Laravel 11 REST API for creating and managing polls with voting functionality.

Features

Authentication

• ✅ JWT-based authentication using Laravel Sanctum
• ✅ User registration, login, logout
• ✅ User profile management
• ✅ Token-based API access

Poll Management

• ✅ Create, read, update, delete polls
• ✅ Poll ownership and authorization
• ✅ Poll scheduling (start/end times)
• ✅ Poll status management (active/inactive)
• ✅ Poll search and filtering

Poll Options

• ✅ Multiple options per poll
• ✅ Option ordering
• ✅ Dynamic option management

Voting System

• ✅ One vote per user per poll (configurable)
• ✅ Anonymous voting support
• ✅ Multiple votes per user (configurable)
• ✅ Vote tracking and management
• ✅ Prevent duplicate voting

Results & Analytics

• ✅ Real-time vote counting
• ✅ Vote percentages calculation
• ✅ Poll results endpoint
• ✅ Vote history tracking

API Features

• ✅ RESTful API design
• ✅ Resource-based responses
• ✅ Comprehensive validation
• ✅ Error handling with standardized format
• ✅ Pagination support
• ✅ Soft deletes

Installation

1. Clone the repository

   git clone <repository-url>
   cd poll-voting-api

2. Install dependencies

   composer install

3. Environment setup

   cp .env.example .env
   php artisan key:generate

4. Database setup

   # Configure your database in .env file
   php artisan migrate
   php artisan db:seed

5. Start the development server

   php artisan serve

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• POST /api/auth/logout - Logout user
• GET /api/auth/user - Get authenticated user

Polls

• GET /api/polls - Get all polls (with filters)
• GET /api/polls/{id} - Get single poll
• POST /api/polls - Create new poll
• PUT /api/polls/{id} - Update poll
• DELETE /api/polls/{id} - Delete poll
• GET /api/polls/{id}/results - Get poll results

Voting

• POST /api/votes/polls/{id} - Cast vote
• GET /api/votes - Get user's votes
• DELETE /api/votes/{id} - Delete vote

Health Check

• GET /api/health - API health status

API Usage Examples

Register User

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "password123",
    "password_confirmation": "password123"
  }'

Create Poll

curl -X POST http://localhost:8000/api/polls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "What is your favorite programming language?",
    "description": "Choose your preferred programming language",
    "start_time": "2024-01-01T10:00:00Z",
    "end_time": "2024-01-07T23:59:59Z",
    "allow_anonymous_voting": true,
    "allow_multiple_votes": false,
    "options": ["JavaScript", "Python", "PHP", "Java"]
  }'

Cast Vote

curl -X POST http://localhost:8000/api/votes/polls/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "poll_option_id": 1
  }'

Get Poll Results

curl -X GET http://localhost:8000/api/polls/1/results \
  -H "Accept: application/json"

Query Parameters

Polls Filtering

• ?active=true - Get only active polls
• ?my_polls=true - Get user's own polls
• ?search=keyword - Search polls by title
• ?page=1 - Pagination

Response Format

All API responses follow this standardized format:

{
  "status": "success|error",
  "message": "Response message",
  "data": {
    // Response data
  },
  "errors": {
    // Validation errors (if any)
  }
}

Authorization

The API uses Laravel Policies for authorization:

• Only poll creators can update/delete their polls
• Users can only delete their own votes
• Anonymous voting is supported when enabled

Database Schema

Users

• id, name, email, password, email_verified_at, remember_token, created_at, updated_at

Polls

• id, title, description, user_id, start_time, end_time, allow_anonymous_voting, allow_multiple_votes, is_active, created_at, updated_at, deleted_at

Poll Options

• id, poll_id, text, order, created_at, updated_at, deleted_at

Votes

• id, poll_id, poll_option_id, user_id, ip_address, user_agent, created_at, updated_at, deleted_at

Testing

The API includes a comprehensive Postman collection (postman_collection.json) with all endpoints and example requests.

Features Implemented

Core Features

• ✅ User authentication and authorization
• ✅ Poll CRUD operations
• ✅ Poll options management
• ✅ Voting system with duplicate prevention
• ✅ Anonymous voting support
• ✅ Real-time results and analytics
• ✅ RESTful API design
• ✅ Comprehensive validation
• ✅ Error handling

Advanced Features

• ✅ Multiple votes per user (configurable)
• ✅ Soft deletes for all entities
• ✅ Poll scheduling and auto-deactivation
• ✅ Search and filtering
• ✅ Pagination
• ✅ IP tracking for anonymous votes
• ✅ Policy-based authorization

Security Features

• ✅ Token-based authentication
• ✅ Input validation and sanitization
• ✅ Authorization policies
• ✅ Rate limiting ready
• ✅ CORS configuration

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is open-sourced software licensed under the MIT license.