📚 Classes API

An unofficial REST API for the New York Public Library (NYPL) TechConnect classes.

This project provides a centralized service for course discovery, information lookup, tracking completed courses, and receiving recommendations.

All course data is publicly available from:

• NYPL TechConnect Classes Page
• TechConnect Google Sites Page

---

📑 Table of Contents

• 💡 Motivation
• 🚀 Getting Started
• 📖 API Overview
• 🔐 Authentication
• 🎓 Courses
• 👤 User Account
• 📡 API Endpoints
• 🧰 Technology Stack
• 🧩 Core Features

💡 Motivation

The NYPL TechConnect site provides a social feed of upcoming classes. While it is great for discovering new sessions, it is difficult to explore the entire catalog of available courses.

The Classes API solves this by providing a centralized, searchable interface for:

• Discovering all TechConnect courses
• Tracking progress and interests
• Building new tools on top of the NYPL TechConnect ecosystem

---

🚀 Getting Started

⚠️ The API is not hosted publicly. You’ll need to run it locally.

Prerequisites

Ensure the following tools are installed:

• docker
• uv
• make

Setup

1. Clone the repository:

git clone https://github.com/TheKangChen/classes-api.git
cd classes-api/backend

2. Start the development environment:

make dev

Run this only the first time. It initializes the database and development environment.

3. Once running, the API server will be available at:

http://localhost:8000/

If the server goes down later, simply run:

make

This will restart the service without clearing existing user data.

---

📖 API Overview

Interactive documentation is available once the server is running:

• Swagger UI: http://localhost:8000/docs
• Redoc: http://localhost:8000/redoc

---

🔐 Authentication

This API uses OAuth2 Password Flow for user authentication.

Register

Send a POST request to:

POST /users/register

Example body:

{
  "username": "<your_username>",
  "password": "<your_password>"
}

Login

Send a POST request to:

POST /token

Example body:

{
  "username": "<your_username>",
  "password": "<your_password>"
}

If successful, you’ll receive:

{
  "access_token": "<your_access_token>",
  "token_type": "bearer"
}

Include this token in the header for authenticated requests:

{
  "Authorization": "Bearer <your_access_token>"
}

---

🎓 Courses

Fetch available course data, including topics/series, formats, and levels.

Examples:

• Get all courses:

GET /courses/all

• Get course by ID:

GET /courses/{course_id}

You’ll receive details such as course description, prerequisites, available handouts, and links to upcoming sessions.

---

👤 User Account

Manage your personal data such as completed courses or topics of interest.

Example: Add completed courses

POST /users/me/courses_taken

{
  "courses_taken": [1, 2, 3, 5]
}

To view your account information:

GET /users/me

Example response:

{
  "username": "your_username",
  "courses_taken": [
    {
      "id": 1,
      "course_name": "Course Name 1"
    },
    {
      "id": 2,
      "course_name": "Course Name 2"
    }
  ],
  "series_interested": [
    {
      "id": 1,
      "series_name": "Topic 1"
    },
    {
      "id": 2,
      "series_name": "Topic 2"
    }
  ]
}

---

📡 API Endpoints

Courses

Method	Endpoint	Description
GET	/courses/all	Fetch all courses (optional filters: level, format, series)
GET	/courses/formats	Fetch all available course formats
GET	/courses/languages	Fetch all available course languages
GET	/courses/levels	Fetch all available course levels
GET	/courses/series	Fetch all available course series
GET	/courses/{course_id}	Fetch course details by ID
GET	/courses/{course_id}/handouts	Fetch course handouts by ID
GET	/courses/{course_id}/additional-materials	Fetch additional materials by ID
GET	/courses/{course_id}/upcoming	Redirect to the upcoming session page

Users

Method	Endpoint	Description
POST	/users/register	Register a new user
POST	/users/reactivate	Reactivate a deactivated account
GET	/users/me	Get current user information
DELETE	/users/me	Deactivate account
POST	/users/me/courses_taken	Add completed courses
DELETE	/users/me/courses_taken	Remove completed courses
POST	/users/me/series_interested	Add interested series
DELETE	/users/me/series_interested	Remove interested series
GET	/users/me/recommendation	Get personalized course recommendations

Authentication

Method	Endpoint	Description
POST	/token	Obtain an access token

---

🧰 Technology Stack

• Backend Framework: FastAPI
• Data Modeling & Validation: Pydantic
• Database & ORM: PostgreSQL with SQLAlchemy
• Data Processing: Pandas for database migration
• Containerization: Docker & Docker Compose for isolated environments
• Testing & CI/CD: Pytest with GitHub Actions for automated testing and deployment
• Development Tools: uv for dependency management and make for simplified task automation

---

🧩 Core Features

• OAuth2 Password Flow with JWT-based authentication
• Rate limiting for all endpoints
• Comprehensive CRUD layer for course, user, and recommendation data
• ORM-backed models with relational mapping via SQLAlchemy
• Database migrations for schema versioning and updates
• Environment-specific configuration (development, testing, production)
• Containerized deployment for reproducible builds
• Automated CI/CD pipeline with tests run through GitHub Actions
• Structured logging to console and file for debugging and observability

---

📍 Road Map

• Chat endpoint to provide natural language support
• Web frontend
• Migrate from hand-rolled database migration to dedicated solution