A comprehensive API for NTHU course management, weather information, venues, and student services built with Hono and TypeScript.
- Overview
- Getting Started
- Authentication
- API Endpoints
- Error Handling
- Rate Limiting
- Examples
- Development
The NTHU Mods API provides access to:
- Course information and scheduling
- Academic calendar events
- Weather forecasts
- Venue information
- Student services integration
- GitHub issue management
- Data synchronization for planner applications
Base URL: https://api.nthumods.com
- Node.js 18+ or Bun runtime
- Valid API keys for external services (when applicable)
npm install
# or
bun install
Required environment variables:
# Database
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_key
# External APIs
CALENDAR_API_KEY=your_google_calendar_api_key
CWA_API_KEY=your_taiwan_weather_api_key
ALGOLIA_APP_ID=your_algolia_app_id
ALGOLIA_API_KEY=your_algolia_api_key
# GitHub Integration
GITHUB_CLIENT_ID=your_github_app_client_id
GITHUB_APP_PRIVATE_KEY=your_github_private_key_base64
GITHUB_INSTALLATION_ID=your_github_installation_id
# Authentication
NTHUMODS_AUTH_INTROSPECTION_URL=auth_introspection_endpoint
NTHUMODS_AUTH_CLIENT_ID=auth_client_id
NTHUMODS_AUTH_CLIENT_SECRET=auth_client_secret
# Other Services
TURNSTILE_SECRET_KEY=cloudflare_turnstile_secret
CLOUDFLARE_WORKER_ACCOUNT_ID=cf_account_id
CLOUDFLARE_KV_SHORTLINKS_NAMESPACE=kv_namespace_id
CLOUDFLARE_KV_API_TOKEN=kv_api_token
Some endpoints require authentication via Bearer tokens:
Authorization: Bearer your_access_token
Authentication is handled through OAuth2 introspection. Protected endpoints include:
- All
/planner/*
endpoints - Some administrative functions
GET /acacalendar?start=2024-01-01&end=2024-12-31
Query Parameters:
start
(required): Start date (YYYY-MM-DD)end
(required): End date (YYYY-MM-DD)
Response:
[
{
"summary": "Spring Semester Begins",
"date": "2024-02-20",
"id": "event_id_123"
}
]
GET /calendar/ical/{userId}?key=api_key&type=basic
Parameters:
userId
(path): User identifierkey
(query): API key for authenticationtype
(query): Calendar type (basic
orfull
, default:basic
)
Response: iCalendar format data
GET /weather
Returns 5-day weather forecast for NTHU area.
Response:
[
{
"date": "2024-01-01",
"weatherData": {
"MinT": "15",
"MaxT": "25",
"PoP12h": "30",
"Wx": "01",
"WeatherDescription": "晴時多雲"
}
}
]
GET /course?courses=11410CS 100101
GET /course?courses[]=11410CS 100101&courses[]=11410EE 200201
GET /course/{courseId}
GET /course/{courseId}/syllabus
Returns course with detailed syllabus, scores, and important dates.
GET /course/{courseId}/minimal
Returns essential course information only.
GET /course/{courseId}/ptt
Scrapes and returns PTT course reviews.
GET /course/{courseId}/related
Returns courses from previous/future semesters with the same course code.
GET /course/classes
Returns list of all available class codes.
GET /course/{courseId}/syllabus/file
Redirects to the course syllabus PDF file.
GET /course/{courseId}/dates
POST /course/{courseId}/dates
Get or update important course dates (POST currently disabled).
GET /venue
GET /venue/{venueId}/courses?semester=11410
PUT /shortlink?url=https://example.com/very/long/url
Response:
https://nthumods.com/l/abc123def
GET /shortlink/{key}
POST /issue
Content-Type: application/json
{
"title": "Bug report: Login not working",
"body": "Detailed description of the issue...",
"labels": ["bug", "high-priority"],
"turnstileToken": "optional_turnstile_token"
}
GET /issue?tag=bug
CCXP (Course and Curriculum eXchange Platform) integration provides access to official NTHU systems.
POST /ccxp/auth/login
Content-Type: application/x-www-form-urlencoded
studentid=your_student_id&password=your_password
POST /ccxp/courses
Content-Type: application/x-www-form-urlencoded
ACIXSTORE=session_token
POST /ccxp/courses/latest
POST /ccxp/grades
Returns comprehensive grade information including GPA, rankings, and course grades.
POST /ccxp/courses/latest-enrollment
- Current enrollment dataPOST /ccxp/courses/hidden-course-selection
- Hidden course selection dataPOST /ccxp/courses/class-detailed
- Detailed class informationPOST /ccxp/eeclass/login
- EEClass OAuth loginPOST /ccxp/inthu/code
- iNTHU service code generationPOST /ccxp/inthu/token
- iNTHU token managementPOST /ccxp/inthu/door-access-qr
- Door access QR codePOST /ccxp/inthu/parcel-information
- Parcel pickup information
RxDB-compatible synchronization endpoints for the planner application. Requires authentication.
GET /planner/folders/pull?id=folder_id&serverTimestamp=2024-01-01T00:00:00Z
POST /planner/folders/push
GET /planner/items/pull?uuid=item_uuid&serverTimestamp=2024-01-01T00:00:00Z
POST /planner/items/push
GET /planner/plannerdata/pull?id=data_id&serverTimestamp=2024-01-01T00:00:00Z
POST /planner/plannerdata/push
GET /planner/semesters/pull?id=semester_id&serverTimestamp=2024-01-01T00:00:00Z
POST /planner/semesters/push
The API uses standard HTTP status codes:
200
- Success400
- Bad Request (invalid parameters)401
- Unauthorized (missing/invalid authentication)403
- Forbidden (insufficient permissions)404
- Not Found500
- Internal Server Error
Error responses follow this format:
{
"error": "Error message",
"code": "ERROR_CODE",
"details": "Additional details"
}
Rate limiting is applied per IP address:
- Standard endpoints: 100 requests per minute
- Authentication endpoints: 10 requests per minute
- Heavy operations (scraping): 5 requests per minute
// Get course information
const response = await fetch('https://api.nthumods.com/course/11410CS100101');
const course = await response.json();
// Create short link
const shortLinkResponse = await fetch('https://api.nthumods.com/shortlink?url=https://example.com', {
method: 'PUT'
});
const shortLink = await shortLinkResponse.text();
// Get weather forecast
const weatherResponse = await fetch('https://api.nthumods.com/weather');
const weather = await weatherResponse.json();
import requests
# Get course information
response = requests.get('https://api.nthumods.com/course/11410CS100101')
course = response.json()
# Create GitHub issue
issue_data = {
'title': 'Bug report',
'body': 'Description of the bug',
'labels': ['bug']
}
response = requests.post('https://api.nthumods.com/issue', json=issue_data)
issue = response.json()
# Get weather forecast
curl https://api.nthumods.com/weather
# Get courses by venue
curl "https://api.nthumods.com/venue/綜合一館/courses?semester=11410"
# Create short link
curl -X PUT "https://api.nthumods.com/shortlink?url=https://example.com"
# Install dependencies
bun install
# Start development server
bun run dev
# Run tests
bun test
# Generate Prisma client
bun run db:generate
# Deploy database migrations
bun run db:push
src/
├── config/ # Configuration files (Supabase, Algolia)
├── headless-ais/ # CCXP system integration
├── scheduled/ # Scheduled tasks (syllabus scraping)
├── types/ # TypeScript type definitions
├── utils/ # Utility functions
├── generated/ # Generated Prisma client
└── prisma/ # Database schema and client
- Copy
.env.example
to.env
- Fill in required environment variables
- Set up Supabase database
- Configure external service API keys
The API includes comprehensive tests for core functionality:
# Run all tests
bun test
# Run specific test file
bun test src/utils/deepCompare.test.ts
# Run tests in watch mode
bun test --watch
The API is designed to run on Cloudflare Workers:
# Deploy to production
wrangler deploy
# Deploy to staging
wrangler deploy --env staging
The API uses Prisma with SQLite/D1 for data persistence. Key models include:
Course
- Course informationFolder
- Planner folder structureItem
- Planner itemsPlannerData
- Planner configurationSemester
- Academic semester data
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
The API includes automated tasks for:
- Course data scraping from CCXP
- Syllabus PDF downloads
- Algolia search index synchronization
These run via Cloudflare Workers Cron Triggers.
Complete OpenAPI 3.0 specification is available in openapi.yaml
. You can use this with tools like:
- Swagger UI
- Postman
- Insomnia
- API documentation generators
For issues and questions:
- GitHub Issues: nthumodifications/courseweb
- Website: nthumods.com
This project is licensed under the MIT License. See the LICENSE file for details.