Activity 11: Quest Tracker API

A complete Express.js REST API for managing quests, players, and categories in a gamified todo system.

⚠️ IMPORTANT: Dependencies Required!

This activity requires npm dependencies (5.8MB node_modules) that are NOT included in the ZIP file.

Local Setup (If Downloaded as ZIP):

# 1. Extract the ZIP file
unzip activity-11-quest-api.zip
cd activity-11-quest-api

# 2. Install dependencies (REQUIRED!)
npm install

# 3. Start the server
npm start

# 4. Open test.html in your browser

Why node_modules is excluded:

• Keeps ZIP size manageable (29K instead of 6MB)
• Ensures you get the latest package versions
• Standard practice in Node.js development

Required packages: express, cors, express-rate-limit, helmet, morgan

Note for Teachers: This is the complete reference implementation. Students receive a version with TODOs to complete.

🚀 Quick Start

1. Click "Fork" to create your own copy
2. Wait for dependencies to install
3. Server will start automatically on port 3000
4. Open test.html to interact with your API

📁 Project Structure

activity-11-quest-api/
├── server.js              # Main Express server
├── routes/
│   ├── quests.js          # Quest management endpoints
│   ├── players.js         # Player profile and stats
│   └── categories.js      # Quest categories and suggestions
├── middleware/            # Custom middleware (ready for expansion)
├── test.html             # Interactive API testing interface
├── package.json          # Dependencies and scripts
└── README.md            # This file

🎯 Learning Objectives

After completing this activity, you'll understand:

• REST API Design: Proper HTTP methods, status codes, and response formats
• Express.js Framework: Routing, middleware, error handling
• API Authentication: API key validation and security
• Rate Limiting: Protecting your API from abuse
• Data Modeling: Structuring quest, player, and category data
• Error Handling: Graceful error responses and validation
• API Documentation: Self-documenting endpoints

🛠️ API Endpoints

🏆 Quest Management

GET /api/quests

Get all quests with filtering and sorting options.

Query Parameters:

• status - Filter by quest status (pending, in_progress, completed)
• priority - Filter by priority (low, medium, high, critical)
• category - Filter by category (work, health, personal, learning, creative)
• tags - Filter by tags (comma-separated)
• difficulty - Filter by difficulty (easy, medium, hard)
• sort_by - Sort field (created_at, priority, deadline, xp_reward)
• order - Sort order (asc, desc)
• limit - Maximum results (1-50)

Example:

GET /api/quests?status=pending&priority=high&sort_by=deadline&limit=10

GET /api/quests/:id

Get detailed information about a specific quest.

Features:

• Days until deadline calculation
• Urgency and overdue indicators
• Difficulty information with visual indicators
• XP reward details

POST /api/quests/:id/complete

Mark a quest as completed and calculate rewards.

Features:

• Base XP + bonus XP for early completion
• Achievement progress tracking
• Completion timestamp

POST /api/quests (Bonus)

Create a new quest with custom parameters.

Required Fields:

• title - Quest title
• description - Quest description (optional)
• category - Quest category
• priority - Quest priority

👤 Player Management

GET /api/players/:username

Get comprehensive player profile and statistics.

Query Parameters:

• include_quests - Include detailed quest information (true/false)
• include_stats - Include calculated statistics (true/false, default true)

Available Players:

• alex - Level 15, experienced player
• jordan - Level 8, intermediate player
• sam - Level 22, veteran player
• demo - Level 1, new player

GET /api/players

Get player leaderboard with rankings.

Query Parameters:

• sort_by - Sort field (level, xp, streak, activity)
• order - Sort order (asc, desc)
• limit - Maximum results (1-50)

Features:

• Leaderboard positions
• Activity scores
• Completion rates
• Achievement counts

📂 Category Management

GET /api/categories

Get all quest categories with optional statistics.

Query Parameters:

• search - Search categories by name, description, or tags
• include_stats - Include quest statistics (true/false)
• sort_by - Sort field (name, popularity, xp_multiplier)

Available Categories:

• 💼 Work & Career - Professional development (1.2x XP)
• 🏃 Health & Fitness - Physical and mental wellness (1.1x XP)
• 🌟 Personal Life - Family, friends, hobbies (1.0x XP)
• 📚 Learning & Skills - Education and skill development (1.3x XP)
• 🎨 Creative Projects - Art, writing, music (1.1x XP)
• 💰 Finance & Money - Budgeting and financial planning (1.2x XP)

GET /api/categories/:id

Get detailed category information with tips and suggestions.

Features:

• Category statistics and trends
• Actionable tips for success
• Getting started guides
• Sample quest suggestions
• Difficulty distributions

🔐 Authentication

API Key Authentication

All /api/* endpoints require authentication via API key.

Demo API Keys:

• demo_key_12345 - Primary demo key
• test_key_67890 - Secondary test key
• student_key_abcde - Student practice key
• dev_key_quickstart - Quick development key

Authentication Methods:

1. Header Method (Recommended):

curl -H "X-API-Key: demo_key_12345" http://localhost:3000/api/quests

2. Query Parameter Method:

curl "http://localhost:3000/api/quests?api_key=demo_key_12345"

Rate Limiting

• 15 minutes window: 100 requests per IP
• Headers included: X-RateLimit-* headers in responses
• Exceeded limit: 429 status with retry information

🧪 Testing Your API

Interactive Test Interface

Open test.html in your browser for a comprehensive testing interface featuring:

• Authentication testing with multiple API keys
• All endpoint coverage with parameter controls
• Error scenario testing for edge cases
• Performance testing with concurrent requests
• Quick test flows for complete API validation
• Real-time statistics tracking request performance

Command Line Testing

Basic curl commands:

# Get server info
curl http://localhost:3000/

# Test authentication
curl -H "X-API-Key: demo_key_12345" http://localhost:3000/api/quests

# Get specific quest
curl "http://localhost:3000/api/quests/1?api_key=demo_key_12345"

# Complete a quest
curl -X POST -H "X-API-Key: demo_key_12345" \
  http://localhost:3000/api/quests/1/complete

# Get player profile
curl "http://localhost:3000/api/players/alex?api_key=demo_key_12345"

# Get categories with stats
curl "http://localhost:3000/api/categories?include_stats=true&api_key=demo_key_12345"

npm Scripts

# Start server
npm start

# Development with auto-reload
npm run dev

# Test endpoints
npm run test

# Health check
npm run health

📊 API Features

Smart Data Enrichment

• Quests: Deadline calculations, urgency indicators, completion percentages
• Players: Dynamic statistics, activity scores, achievement progress
• Categories: Popularity trends, difficulty distributions, usage insights

Comprehensive Error Handling

• 400 Bad Request: Invalid parameters or malformed data
• 401 Unauthorized: Missing or invalid API key
• 404 Not Found: Resource doesn't exist with helpful suggestions
• 429 Too Many Requests: Rate limit exceeded with retry information
• 500 Internal Server Error: Server-side errors with request tracking

Performance Optimizations

• Response caching: Intelligent data caching strategies
• Request logging: Comprehensive request/response logging
• Memory monitoring: Built-in memory usage tracking
• Connection management: Efficient connection handling

Security Features

• Helmet.js: Security headers protection
• CORS configuration: Controlled cross-origin access
• Input validation: Parameter validation and sanitization
• Rate limiting: IP-based request throttling

🎯 Try These Challenges

Easy Challenges

1. Add new quest fields like tags, difficulty, or estimated_time
2. Create custom API keys and test different access levels
3. Add quest search functionality by title or description

Medium Challenges

1. Implement quest updates with PUT /api/quests/:id
2. Add quest deletion with proper cascade handling
3. Create player achievements system with unlock conditions

Hard Challenges

1. Add database integration with MongoDB or PostgreSQL
2. Implement user registration and JWT authentication
3. Add real-time notifications with WebSocket connections
4. Create API versioning (v1, v2) with backward compatibility

🚀 Extension Ideas

Advanced Features

• Quest Dependencies: Link quests together in sequences
• Team Quests: Collaborative quests for multiple players
• Quest Templates: Reusable quest blueprints
• Habit Tracking: Recurring quest patterns
• Achievement System: Unlockable badges and titles

Integration Opportunities

• Calendar Integration: Sync quest deadlines with calendars
• Notification Services: Email/SMS reminders for deadlines
• Analytics Dashboard: Quest completion analytics
• Social Features: Quest sharing and leaderboards
• Mobile App: React Native or Flutter companion app

📚 Code Architecture

Modular Design

• Routes: Separated by feature area (quests, players, categories)
• Middleware: Reusable authentication and logging components
• Data Models: Structured data with validation
• Error Handling: Centralized error processing

Best Practices Implemented

• RESTful Design: Proper HTTP methods and status codes
• Consistent Responses: Standardized API response format
• Documentation: Self-documenting endpoints with examples
• Testing: Built-in test interface and curl examples
• Logging: Comprehensive request/response logging

Scalability Considerations

• Stateless Design: No server-side session storage
• Caching Ready: Prepared for Redis or memory caching
• Database Ready: Structured for easy database integration
• Load Balancer Friendly: Stateless and health-check enabled

🛠️ Development Tips

Adding New Endpoints

1. Create route handler in appropriate routes file
2. Add authentication if needed (most endpoints need it)
3. Implement validation for request parameters
4. Add error handling with appropriate status codes
5. Update test interface in test.html
6. Document in API docs endpoint

Debugging

• Console logging: Server logs all requests and errors
• Health check: /health endpoint shows server status
• Stats endpoint: /api/stats shows performance metrics
• Test interface: test.html shows real-time request/response data

Common Issues

• Port conflicts: Change PORT in server.js if 3000 is busy
• API key errors: Verify key is included in request headers or query
• CORS issues: Check origin URLs in CORS configuration
• JSON parsing: Ensure Content-Type header is set for POST requests

🎉 What You'll Learn

By completing this activity, you'll have hands-on experience with:

• Building production-ready REST APIs with Express.js
• Implementing authentication and security best practices
• Designing clean, consistent API responses
• Handling errors gracefully with proper HTTP status codes
• Creating comprehensive API documentation
• Testing APIs with interactive interfaces
• Understanding rate limiting and performance optimization
• Structuring scalable backend applications

🔗 Related Resources

• Express.js Documentation
• REST API Best Practices
• HTTP Status Codes
• API Authentication Methods

Ready to build amazing APIs? Start your server and open test.html to begin testing! 🚀