Project 03: Quest Tracker REST API

ℹ️ Project Overview Duration: 2 weeks Difficulty: Intermediate Focus: Backend development with Express.js (extending Template 11) Type: Individual project

🚀 Getting Started

This project builds upon Template 11: Quest Tracker API located at /Templates/activity-11-quest-api/. You'll extend the existing gamified quest system with advanced features.

What's Already Built in Template 11

• ✅ Basic Quest Management: CRUD operations for quests with gamification (XP, levels, achievements)
• ✅ Player Profiles: Player statistics, leaderboards, and progress tracking
• ✅ Quest Categories: Organized quest types with XP multipliers
• ✅ API Authentication: Basic API key authentication system
• ✅ Rate Limiting: Protection against API abuse
• ✅ Error Handling: Comprehensive error responses
• ✅ Interactive Testing: Built-in test interface (test.html)

Your Mission: Extend the Foundation

You'll transform Template 11's in-memory system into a production-ready API with persistent storage, user management, and social features.

🎯 Learning Objectives

By completing this project, you will:

• Extend an existing codebase with advanced features
• Implement user authentication and authorization
• Integrate database storage (MongoDB/PostgreSQL)
• Build social features (sharing, leaderboards)
• Deploy a production-ready API to the cloud
• Test API endpoints comprehensively
• Apply concepts from Lessons 11-12 (Building APIs and Deployment)

📋 Project Requirements

Extend Template 11's Quest Tracker API with production-ready features that transform it from a demo into a scalable application.

Core Features (Must Have)

• User Authentication System

  • User registration and login endpoints
  • JWT token-based authentication (replace basic API keys)
  • Password hashing with bcrypt
  • Protected routes for user-specific data

• Database Integration

  • Replace in-memory storage with MongoDB or PostgreSQL
  • Persistent quest, player, and achievement data
  • Database migrations and seeding
  • Data backup and recovery

• Enhanced Quest Management

  • Quest ownership (users can only modify their quests)
  • Quest sharing between players
  • Quest templates for common patterns
  • Recurring quest support (daily/weekly habits)

• Advanced Player Features

  • Personal player profiles with customization
  • Achievement unlock notifications
  • Player statistics dashboard
  • Activity feed and quest history

Advanced Features (Should Have)

• Social Features

  • Global leaderboards with ranking systems
  • Player-to-player quest sharing
  • Public quest galleries
  • Achievement showcases

• Quest Discovery

  • Advanced search with filters (difficulty, category, XP range)
  • Quest recommendations based on player history
  • Trending quests and popular categories
  • Quest completion analytics

• Enhanced Security

  • Input validation and sanitization
  • Role-based access control (admin/user)
  • API rate limiting per user
  • Security headers and CORS configuration

• Performance Optimization

  • Response caching for frequently accessed data
  • Database query optimization
  • Pagination for large datasets
  • API versioning (/api/v1/, /api/v2/)

Bonus Features (Nice to Have)

• Real-time Features

  • WebSocket connections for live updates
  • Real-time achievement notifications
  • Live leaderboard updates
  • Quest completion celebrations

• Advanced Analytics

  • Player engagement metrics
  • Quest completion trends
  • Category popularity analytics
  • Performance dashboards

• Integration Features

  • Email notifications for achievements
  • Calendar integration for quest deadlines
  • Mobile app API endpoints
  • Third-party integrations (Slack, Discord)

🔧 API Endpoints Specification

Base URL: http://localhost:3000/api

Authentication (New JWT System)

• Headers Required: Authorization: Bearer <jwt_token>
• Legacy Support: Template 11's API keys still work for backward compatibility

Quest Endpoints (Extended from Template 11)

Player/User Endpoints (Enhanced)

Social & Discovery Endpoints (New)

Response Format (Enhanced)

{
  "success": true,
  "data": {
    "id": "quest_123",
    "title": "Master Express.js",
    "description": "Build three production APIs",
    "category": "learning",
    "difficulty": "medium",
    "xp_reward": 250,
    "status": "in_progress",
    "owner": {
      "id": "player_456",
      "username": "alex_coder",
      "level": 15
    },
    "sharing": {
      "is_public": true,
      "likes": 42,
      "clones": 8
    },
    "progress": {
      "percentage": 60,
      "days_remaining": 5,
      "urgency": "medium"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z"
  },
  "message": "Quest retrieved successfully",
  "meta": {
    "player_can_edit": true,
    "player_can_share": true,
    "achievement_progress": ["api_builder", "quest_master"]
  }
}

📅 Weekly Milestones

Week One: Foundation & Authentication

Goal: Extend Template 11 with user authentication and database integration

Day 1-2: Project Setup & Analysis

• Copy Template 11 to your development environment
• Study existing codebase and API structure
• Set up development database (MongoDB or PostgreSQL)
• Plan database schema for users, quests, and achievements
• Create new Git repository for your extended version

Day 3-4: User Authentication System

• Implement user registration endpoint (POST /auth/register)
• Add password hashing with bcrypt
• Create login endpoint with JWT generation (POST /auth/login)
• Add JWT middleware for protected routes
• Test authentication flow with Postman/Thunder Client

Day 5-7: Database Integration

• Replace in-memory data with database models
• Migrate existing quest data structure to database
• Implement user-specific quest ownership
• Add database seeding with sample data
• Test all existing Template 11 endpoints with database

Week 2: Social Features & Deployment

Goal: Add social features, quest sharing, and deploy to production

Day 8-10: Social Features

• Implement quest sharing system (POST /quests/:id/share)
• Add quest cloning functionality (POST /quests/:id/clone)
• Create quest discovery endpoints (GET /discover/*)
• Build player following system
• Add social activity feed

Day 11-12: Enhanced Features

• Implement advanced quest search and filtering
• Add quest templates system
• Create achievement notifications
• Build leaderboard enhancements
• Add quest analytics and trends

Day 13-14: Deployment & Documentation

• Deploy to Railway, Render, or Heroku
• Configure production database
• Create comprehensive API documentation
• Set up monitoring and logging
• Final testing of deployed API
• Submit project with demo

🗂️ Project Structure (Extended from Template 11)

quest-tracker-api-extended/
├── package.json
├── .gitignore
├── .env.example
├── README.md
├── server.js                    # Enhanced from Template 11
├── database/
│   ├── connection.js           # NEW: Database connection
│   ├── models/                 # NEW: Database models
│   │   ├── User.js
│   │   ├── Quest.js
│   │   └── Achievement.js
│   └── migrations/             # NEW: Database migrations
├── middleware/
│   ├── auth.js                 # NEW: JWT authentication
│   ├── validation.js           # Enhanced validation
│   └── errorHandler.js         # From Template 11
├── routes/
│   ├── quests.js              # Extended from Template 11
│   ├── players.js             # Extended from Template 11
│   ├── categories.js          # From Template 11
│   ├── auth.js                # NEW: Authentication routes
│   ├── social.js              # NEW: Social features
│   └── discover.js            # NEW: Quest discovery
├── controllers/
│   ├── questController.js     # NEW: Quest business logic
│   ├── userController.js      # NEW: User management
│   ├── socialController.js    # NEW: Social features
│   └── authController.js      # NEW: Authentication logic
├── utils/
│   ├── jwt.js                 # NEW: JWT utilities
│   ├── validation.js          # NEW: Input validation
│   └── emailService.js        # NEW: Email notifications
├── tests/
│   ├── auth.test.js           # NEW: Authentication tests
│   ├── quests.test.js         # Enhanced from Template 11
│   └── social.test.js         # NEW: Social feature tests
└── docs/
    ├── API.md                 # NEW: Complete API documentation
    └── DEPLOYMENT.md          # NEW: Deployment guide

🧪 Testing Requirements

Manual Testing with Postman/Thunder Client

Create comprehensive test collections for:

Authentication Testing

• Register new player with valid data
• Register with invalid data (test validation)
• Login with correct credentials
• Login with wrong credentials
• Access protected routes with JWT token
• Access protected routes without token
• Test token expiration

Quest Management Testing

• Create quest with valid data
• Create quest with invalid data
• Get user's quests (authenticated)
• Get specific quest by ID (ownership validation)
• Update quest (owner only)
• Delete quest (owner only)
• Share quest publicly
• Clone shared quest

Social Features Testing

• Browse public quests
• Like a shared quest
• Follow another player
• Get social activity feed
• Get trending quests
• Get personalized recommendations

Legacy API Testing

• Test Template 11 endpoints still work
• Verify backward compatibility with original API keys
• Test quest categories and player leaderboards

Test Scenarios

1. Authentication Flow: Complete user journey from registration to authenticated requests
2. Quest Ownership: Users can only modify their own quests
3. Social Features: Quest sharing and discovery work correctly
4. Database Persistence: Data survives server restarts
5. Performance: API handles concurrent users efficiently
6. Security: Proper access controls and data validation

🚀 Deployment Instructions

Option One: Railway (Recommended for databases)

1. Create account at railway.app
2. Connect your GitHub repository
3. Add database service (MongoDB/PostgreSQL)
4. Configure environment variables
5. Deploy with automatic CI/CD

Option 2: Render

1. Create account at render.com
2. Create new Web Service
3. Connect GitHub repository
4. Add database add-on
5. Configure environment and deploy

Option 3: Heroku (Free tier alternatives)

1. Use Heroku alternatives like Railway or Render
2. Configure database add-ons
3. Set up environment variables
4. Deploy with Git integration

Environment Variables

PORT=3000
JWT_SECRET=your-super-secret-jwt-key
DATABASE_URL=your-database-connection-string
NODE_ENV=production
CORS_ORIGIN=https://your-frontend-domain.com
EMAIL_SERVICE_API_KEY=your-email-service-key (optional)

📊 Grading Rubric

📚 Resources & References

Course Materials

• Template 11: Quest Tracker API - Your starting foundation
• Concept 11: Building APIs with Express.js
• Concept 12: API Deployment and DevOps

Technical Documentation

• Express.js Official Documentation
• JWT Authentication Guide
• MongoDB Atlas Documentation
• PostgreSQL Documentation
• bcrypt Library for Password Hashing

API Design & Testing

• REST API Design Best Practices
• HTTP Status Codes Reference
• Postman API Testing Guide
• API Authentication Patterns

Deployment Platforms

• Railway Deployment Guide
• Render Deployment Guide
• Database Hosting Options

💡 Development Tips

Getting Started with Template 11

1. Understand the foundation: Study Template 11's code structure and API design
2. Test the original: Use the test.html interface to understand existing functionality
3. Plan your extensions: Map out which features you'll add without breaking existing ones
4. Backup compatibility: Ensure Template 11's original endpoints still work

Extension Strategy

• Start small: Add authentication first, then database, then social features
• Maintain compatibility: Don't break existing API keys or endpoints
• Use middleware: Leverage Express middleware for cross-cutting concerns
• Database first: Set up your database schema before adding complex features

Common Pitfalls to Avoid

• Breaking Template 11: Don't modify core functionality without understanding dependencies
• Security gaps: Validate all user input, especially in social features
• Database performance: Use indexes and efficient queries for quest searches
• Authentication bypass: Ensure all new endpoints are properly protected

Quest Tracker Specific Tips

• Preserve gamification: Keep the XP, levels, and achievement systems intact
• Enhance, don't replace: Build on Template 11's quest categories and player system
• Social features security: Validate quest sharing permissions and privacy settings
• Performance scaling: Consider caching for leaderboards and popular quests

📝 Submission Requirements

What to Submit

1. GitHub Repository: Extended Quest Tracker API with clear README
2. Deployed API: Live URL to your enhanced Quest Tracker
3. API Documentation: Complete endpoint guide including new features
4. Postman Collection: Test collection for authentication and social features
5. Extension Report: 2-3 page summary of:
   • How you extended Template 11
   • New features implemented
   • Technical challenges and solutions
   • Database design decisions
   • Future enhancement ideas

Demonstration Requirements

Your deployed API should demonstrate:

• Working authentication: Registration, login, and protected routes
• Database persistence: Data survives server restarts
• Social features: Quest sharing and discovery
• Backward compatibility: Template 11's original features still work
• Professional deployment: Proper environment configuration and monitoring

Submission Format

Submit your project through the course submission form including:

• GitHub repository link (must include setup instructions)
• Deployed API URL (with sample credentials for testing)
• API documentation link
• Brief video demo (2-3 minutes) showing key features
• Extension report highlighting your contributions

Submit Your Quest Tracker API Here

💡 Pro Tip: Think of this as evolving Template 11 into a production system. Your users are already familiar with the quest system - enhance their experience with authentication, persistence, and social features while keeping what they love about the original!