Gradescope Microservice

A Flask-based REST API microservice that provides Gradescope integration using the unofficial gradescopeapi Python library.

Features

• Fetch all courses for a user
• Fetch assignments across all courses or for specific courses
• Get submission details
• Session caching for performance
• Error handling and logging
• CORS enabled for cross-origin requests

Installation

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Install the gradescopeapi library:

# If you have the gradescopeapi library locally
pip install /path/to/gradescopeapi

# Or if available on PyPI
pip install gradescopeapi

Running Locally

python app.py

The service will start on http://localhost:5000

Running in Production

Use gunicorn for production:

gunicorn -w 4 -b 0.0.0.0:5000 app:app

API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "service": "gradescope-api"
}

Get All Courses

POST /api/courses
Content-Type: application/json

{
  "email": "student@ucdavis.edu",
  "password": "your_password"
}

Response:

{
  "courses": [
    {
      "id": "123456",
      "name": "ECS 36A",
      "full_name": "Programming & Problem Solving",
      "semester": "Fall",
      "year": "2024",
      "num_assignments": 10,
      "num_grades_published": 5
    }
  ]
}

Get All Assignments

POST /api/assignments
Content-Type: application/json

{
  "email": "student@ucdavis.edu",
  "password": "your_password"
}

Response:

{
  "assignments": [
    {
      "course_id": "123456",
      "course_name": "ECS 36A",
      "assignment_id": "789",
      "assignment_name": "Homework 1",
      "due_date": "2024-10-15T23:59:00",
      "release_date": "2024-10-08T00:00:00",
      "total_points": 100,
      "submission_status": "submitted",
      "url": "https://www.gradescope.com/courses/123456/assignments/789"
    }
  ],
  "count": 15
}

Get Course Assignments

POST /api/assignments/{course_id}
Content-Type: application/json

{
  "email": "student@ucdavis.edu",
  "password": "your_password"
}

Get Submission Details

POST /api/submission/{course_id}/{assignment_id}
Content-Type: application/json

{
  "email": "student@ucdavis.edu",
  "password": "your_password",
  "student_email": "student@ucdavis.edu"
}

Logout (Clear Cache)

POST /api/logout
Content-Type: application/json

{
  "email": "student@ucdavis.edu"
}

Integration with Firebase Cloud Functions

Update your fetchGradescopeAssignments Cloud Function to call this service:

// In fetchGradescopeAssignments.js
const GRADESCOPE_SERVICE_URL = 'http://localhost:5000'; // or your deployed URL

const response = await axios.post(`${GRADESCOPE_SERVICE_URL}/api/assignments`, {
  email: gradescopeEmail,
  password: gradescopePassword
});

const assignments = response.data.assignments;

Deployment Options

Option 1: Google Cloud Run

gcloud run deploy gradescope-service \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

Option 2: Heroku

heroku create gradescope-service
git push heroku main

Option 3: AWS Lambda with Zappa

Install Zappa:

pip install zappa
zappa init
zappa deploy production

Option 4: Docker

docker build -t gradescope-service .
docker run -p 5000:5000 gradescope-service

Security Considerations

⚠️ Important Security Notes:

1. Authentication: Add authentication to prevent unauthorized access
2. Rate Limiting: Implement rate limiting to prevent abuse
3. Encryption: Use HTTPS for all communications
4. Credentials: Never store plain-text passwords
5. Session Management: Implement proper session timeout
6. Logging: Log all access attempts for security auditing

Environment Variables

Create a .env file:

FLASK_ENV=production
SECRET_KEY=your-secret-key
PORT=5000

Testing

# Test health check
curl http://localhost:5000/health

# Test courses endpoint
curl -X POST http://localhost:5000/api/courses \
  -H "Content-Type: application/json" \
  -d '{"email":"student@ucdavis.edu","password":"your_password"}'

# Test assignments endpoint
curl -X POST http://localhost:5000/api/assignments \
  -H "Content-Type: application/json" \
  -d '{"email":"student@ucdavis.edu","password":"your_password"}'

Troubleshooting

Connection Issues

• Verify Gradescope credentials are correct
• Check if Gradescope website is accessible
• Ensure gradescopeapi library is installed correctly

Performance Issues

• Connection caching is enabled by default
• Consider implementing Redis for distributed caching
• Monitor memory usage for cache

API Changes

• Gradescope may update their website structure
• Monitor gradescopeapi library for updates
• Implement fallback mechanisms

License

This is an unofficial integration and is not affiliated with Gradescope.