• Overview
• Project Structure
• API Endpoints
• API Documentation
• Testing
• Grading Criteria
• Getting Started
• Contact & Support
• Contributors

Welcome to the V.A.S.T. Coding Hackathon hosted by the Academic Association of Mathematics & Computer Science of University of Isfahan (A.M.C.S.U.I.) ! 🎓

In this exciting challenge, teams of up to 4 participants will design, develop, and deploy a robust API using any programming language or framework of their choice. 💻

• Create a secure 🔒 and efficient ⚡ API
• Implement proper authentication
• Handle rate limiting and security measures
• Dockerize the application 🐳
• Pass all provided test cases 🧪

Your API's logic and performance will be evaluated based on:

• Test case pass rate
• Code quality and organization
• Security implementation
• Error handling
• Documentation quality

vast-game/
├── src/ # Source code
├── test/ # Test cases
├── runner.sh # Test runner script
└── setup.sh # Setup script

1. Register a new user
2. Login to get JWT token
3. Use token for protected routes
4. Logout to invalidate token

POST /login

Headers

Content-Type: application/json

Body

{
"email": "user@example.com",
"password": "StrongPass123!"
}

Parameters

Responses

Test Requirements:

• Email validation (must be valid email format)
• Password validation (min 8 characters, special chars, numbers, uppercase)
• Email existence check
• Password correctness verification
• Rate limit: 4 requests per minute

POST /register

Headers

Content-Type: application/json

Body

{
"email": "user@example.com",
"password": "StrongPass123!"
}

Parameters

Responses

Test Requirements:

• Email validation (must be valid email format)
• Password validation (min 8 characters, special chars, numbers, uppercase)
• Email uniqueness check
• Rate limit: 4 requests per minute

POST /logout

Headers

Authorization: Bearer <token>

Responses

Test Requirements:

• Token validation
• Token invalidation after logout
• Rate limit: 4 requests per minute

GET /protected

Headers

Authorization: Bearer <token>

Responses

Test Requirements:

• Token validation
• Token expiration handling
• Rate limit: 4 requests per minute

GET /profile

Headers

Authorization: Bearer <token>

Responses

Test Requirements:

• Token validation
• User data retrieval
• Rate limit: 4 requests per minute

POST /forget-password

Headers

Content-Type: application/json

Body

{
"email": "user@example.com"
}

Parameters

Responses

Test Requirements:

• Email validation (must be valid email format)
• Email existence check
• Rate limit: 4 requests per minute
• Should not reveal if email exists in the system
• Should send password reset email if email exists

1. Download NodeJs
2. Clone the repository

   cdtest

3. Install dependencies:

   npm install

4. Run the tests:

   npm test

1. Authentication Tests (100 points)

   • Registration Tests (25 points)
   • Login Tests (25 points)
   • Protected Route Tests (15 points)
   • Logout Tests (15 points)
   • Password Reset Tests (20 points)

2. Security Tests

   • Rate limiting
   • Token validation
   • Password strength
   • Input validation

{
"test_user": {
"email": "test@example.com",
"password": "Test123!@#"
},
"test_tokens": {
"valid": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expired": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"invalid": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}

• Authentication (100 points)
  • Registration: 25 points
  • Login: 25 points
  • Protected Routes: 15 points
  • Logout: 15 points
  • Password Reset: 20 points

• Test case pass rate
• Code quality and organization
• Security implementation
• Error handling
• Documentation quality
• API design and structure

First, ensure you have the necessary tools installed:

• Node.js (v14 or higher)
• Docker (for containerization)
• Git (for version control)
• A code editor (we recommend VS Code)

Then run the setup script:

./setup.sh

To verify your environment is working correctly:

./runner.sh

Select your preferred programming language and framework. Here are some recommended options:

• Node.js/Express: Express.js Documentation
• Python/FastAPI: FastAPI Documentation
• Go/Gin: Gin Web Framework
• Java/Spring: Spring Boot

2. API Implementation

   • Implement all required endpoints as specified in the API Documentation
   • Follow RESTful API best practices
   • Use proper HTTP status codes
   • Implement comprehensive error handling

3. Security Measures 🔒

   • Implement JWT authentication
   • Add rate limiting (4 requests/minute)
   • Use secure password hashing (e.g., bcrypt)
   • Implement input validation
   • Add CORS protection
   • Use environment variables for sensitive data

4. Testing Your Implementation

   • Write unit tests for your endpoints
   • Test edge cases and error scenarios
   • Verify rate limiting functionality
   • Test authentication flow
   • Run the provided test suite

1. Create Dockerfile Create a Dockerfile in your src directory:

   # Example for Node.js applicationFROM node:18-alpine
   WORKDIR /app
   COPY package*.json ./
   RUN npm install
   COPY . .
   EXPOSE 8000
   CMD ["npm", "start"]

2. Docker Requirements

   • Your service must be self-contained (no external dependencies)
   • No database or external service dependencies
   • Must run on port 8000 inside the container
   • Environment variables should be handled within the container
   • Use multi-stage builds for smaller image size

3. Building and Running

   # Build the Docker image
   docker build -t vast-api src/
   # Run the container
   docker run -p 8000:8000 vast-api

4. Best Practices

   • Use .dockerignore to exclude unnecessary files
   • Implement health checks
   • Use non-root user in container
   • Optimize layer caching
   • Keep images small and secure

• All endpoints implemented and tested
• Rate limiting configured (4 requests/minute)
• Authentication working correctly
• Error handling implemented
• Dockerfile created and tested
• Container runs without external dependencies
• Service accessible on port 8000
• All tests passing

• Docker Documentation
• Docker Best Practices
• JWT Authentication Guide
• Rate Limiting Patterns
• API Security Best Practices

• 📧 Email: amcsui.ir@gmail.com
• 💬 Support: @AMCSSup
• 💬 Event Group: @VAST_event
• 💬 Telegram: @AMCSUI
• 📚 Wiki: wiki.amcsui.ir