sfucourses-api

REST API server for SFU course outlines, sessions, instructors, and reviews
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Features
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

Unofficial API for accessing SFU course outlines, sections, and instructors robustly and used to power sfucourses.com. Data is pulled from SFU Course Outlines REST API. This API is not affiliated with Simon Fraser University.

See api.sfucourses.com

(back to top)

Built With

• Golang

(back to top)

Getting Started

To get a local copy up and running follow these simple example steps.

Prerequisites

• Golang v1.23.3

Quick Features

• REST API Server - api.sfucourses.com
• Golang Script to fetch outlines, sessions, and sync instructors

Installation

1. Clone the repo

   git clone https://github.com/brianrahadi/sfucourses-api.git

2. Change git remote url to avoid accidental pushes to base project

   git remote set-url origin brianrahadi/sfucourses-api
   git remote -v

3. Run the project through air.toml or docker

air is good for development with it's real-time file update sync

air

Docker is good for its 1-to-1 behaviour with production. You can either use docker build and run or docker compose.

(back to top)

Docker

Build the Image

docker build -t sfu-courses-api .

Run the Container

docker run -p 8080:8080 sfu-courses-api

Useful Docker Commands

# View running containers
docker ps

# View logs
docker logs <container_id>

# View logs live
docker logs -f <container_id>

# Stop container
docker stop <container_id>

# Remove container
docker rm <container_id>

The API will be available at http://localhost:8080 once the container is running.

Prerequisite data

Prerequisites are parsed from SFU's catalog text with a deterministic parser (internal/prereq) when the API loads outlines.json, so there is no generated file to keep in sync. Two endpoints expose it:

• GET /v1/rest/prerequisites – full and/or trees per course, including UNITS:, PERMISSION: and COREQUISITE: leaves.
• GET /v1/rest/prerequisites/graph – flat {dept, number, prerequisites[], corequisites[]} entries used by the sfucourses.com graph. Recommended courses and "may not take for further credit" exclusions are left out; retired subject aliases such as FPA in CA (or FPA) 160 are dropped when a current alternative exists.

Weekly refresh. .github/workflows/prereqs.yml runs every Monday (after the RMP refresh). scripts/syncPrereqs reads the next, current and previous term from the SFU outlines API, updates only the prerequisites/corequisites fields in outlines.json (and adds courses that are new), writes prereq_meta.json (served as lastPrereqUpdate on /health), and commits. The push redeploys the API, which then asks sfucourses.com to revalidate /graph. The job aborts without writing if the SFU API looks down, and the step summary lists every text change and any newly unparseable entries.

make sync-prereqs-dry   # report what would change
make sync-prereqs       # update outlines.json and prereq_meta.json

When the parser gets one wrong, add the course to internal/store/json/prereq_overrides.json with corrected text (the parser still builds the tree) and a reason:

{ "CRIM 480": { "prerequisites": "CRIM 380.", "reason": "Catalog typo: 'CRlM 380'" } }

Roadmap

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Very recommended! very appreciated!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Docker Commands

### UPDATE_PASSWORD
Required for the `/update` endpoint. Set this environment variable to secure manual data updates.

```bash
export UPDATE_PASSWORD="your-secure-password-here"

Usage:

curl -X POST http://localhost:8080/update \
  -H "Content-Type: text/plain" \
  -d "your-secure-password-here"

Security Note: Never commit the actual password to version control. Use environment variables or secrets management in production.

Git Hooks

To set up the pre-commit hooks:

cp hooks/pre-commit .git/hooks/
chmod +x .git/hooks/pre-commit

This way:

• The hook templates are version controlled
• Each developer can set up their own hooks
• The actual .git/hooks directory remains local to each developer's machine

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Brian Rahadi - brian.rahadi@gmail.com

Project Link: https://github.com/brianrahadi/sfucourses-api

(back to top)

Acknowledgments

• https://go.dev/doc/ - Golang Dev docs

(back to top)