openapi: 3.0.2
info:
title: Penn Courses API Documentation
version: ''
description: '
# Introduction
Penn Courses ([GitHub](https://github.com/pennlabs/penn-courses)) is the umbrella
categorization for [Penn Labs](https://pennlabs.org/)
products designed to help students navigate the course registration process. It currently
includes three products, each with their own API documented on this page:
Penn Course Alert, Penn Course Plan, and Penn Course Review.
See `Penn Labs Notion > Penn Courses` for more details on each of our (currently) three apps.
For instructions on how to maintain this documentation while writing code,
see the comments in `backend/PennCourses/docs_settings.py` (it is easy, and will be helpful
for maintaining Labs knowledge in spite of our high member turnover rate).
See our [GitHub](https://github.com/pennlabs/penn-courses) repo for instructions on
installation, running in development, and loading in course data for development. Visit
the `/admin/doc/` route ([link](/admin/doc/)) for the backend documentation generated by Django
(admin account required, which can be made by running
`python manage.py createsuperuser` in terminal/CLI).
# Unified Penn Courses
By virtue of the fact that all Penn Courses products deal with, well, courses,
it would make sense for all three products to share the same backend.
We realized the necessity of a unified backend when attempting to design a new Django backend
for Penn Course Plan. We like to live by the philosophy of keeping it
[DRY](https://en.wikipedia.org/wiki/Don''t_repeat_yourself), and
PCA and PCP''s data models both need to reference course and
section information. We could have simply copied over code (a bad idea)
or created a shared reusable Django app (a better idea) for course data,
but each app would still need to download copies of the same data.
Additionally, this will help us build integrations between our Courses products.
# Authentication
PCx user authentication is handled by platform''s Penn Labs Accounts Engine.
See [Penn Labs Notion > Platform > The Accounts Engine](https://www.notion.so/pennlabs/The-Accounts-Engine-726ccf8875e244f4b8dbf8a8f2c97a87?pvs=4)
for extensive documentation and links to repositories for this system. When tags or routes
are described as requiring user authentication, they are referring to this system.
I highly recommend the [official video course on OAuth2](https://oauth.net/2/) (by Aaron Parecki),
then the Platform Notion docs on the "Accounts Engine" for anyone who wants to understand
Labs authentication better. Platform is our OAuth2 "Authorization Server",
and Django Labs Accounts is an OAuth2 client run by our Django backends (Clubs, Penn Courses, etc),
exposing client-facing authentication routes like `penncourseplan.com/accounts/login`.
There''s also this Wikipedia page explaining [Shibboleth](https://en.wikipedia.org/wiki/Shibboleth_(software))
(which is used by Penn for authentication, and by the Platform authorization server).
See the Django docs for more on Django''s features for
[User Authentication](https://docs.djangoproject.com/en/3.0/topics/auth/),
which are used by PCX apps, as part of Platform''s accounts system.
'
x-logo:
url: https://i.imgur.com/tVsRNxJ.png
altText: Labs Logo
contact:
email: [email protected]
paths:
/accounts/me/:
get:
operationId: Retrieve User
description: '(GET `/accounts/me/`)
This view exposes the Penn Labs Accounts User object.
<span style="color:red;">User authentication required</span>.'
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
username:
type: string
readOnly: true
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
first_name:
type: string
maxLength: 150
last_name:
type: string
maxLength: 150
profile:
type: object
properties:
email:
type: string
format: email
nullable: true
description: The email of the User. Defaults to null.
maxLength: 254
phone:
type: string
nullable: true
description: '
The phone number of the user. Defaults to null.
The phone number will be stored in the E164 format, but any form parseable by
the
[phonenumbers library](https://pypi.org/project/phonenumbers/)
will be accepted and converted to E164 format automatically upon saving.
'
maxLength: 100
push_notifications:
type: boolean
description: '
Defaults to False, changed to True if the User enables mobile push notifications
for PCA, rather than text notifications.
'
description: The user profile object, storing collected info about the user.
description: ''
'403':
description: Access denied (missing or improper authentication).
tags:
- '[Accounts] User'
put:
operationId: Update User
description: '(PUT `/accounts/me/`)
This view exposes the Penn Labs Accounts User object.
<span style="color:red;">User authentication required</span>.'
parameters: []
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
readOnly: true
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
first_name:
type: string
maxLength: 150
last_name:
type: string
maxLength: 150
profile:
type: object
properties:
email:
type: string
format: email
nullable: true
description: The email of the User. Defaults to null.
maxLength: 254
phone:
type: string
nullable: true
description: '
The phone number of the user. Defaults to null.
The phone number will be stored in the E164 format, but any form parseable by
the
[phonenumbers library](https://pypi.org/project/phonenumbers/)
will be accepted and converted to E164 format automatically upon saving.
'
maxLength: 100
push_notifications:
type: boolean
description: '
Defaults to False, changed to True if the User enables mobile push notifications
for PCA, rather than text notifications.
'
description: The user profile object, storing collected info about the user.
responses:
'200':
content:
application/json:
schema:
type: object
properties:
username:
type: string
readOnly: true
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
first_name:
type: string
maxLength: 150
last_name:
type: string
maxLength: 150
profile:
type: object
properties:
email:
type: string
format: email
nullable: true
description: The email of the User. Defaults to null.
maxLength: 254
phone:
type: string
nullable: true
description: '
The phone number of the user. Defaults to null.
The phone number will be stored in the E164 format, but any form parseable by
the
[phonenumbers library](https://pypi.org/project/phonenumbers/)
will be accepted and converted to E164 format automatically upon saving.
'
maxLength: 100
push_notifications:
type: boolean
description: '
Defaults to False, changed to True if the User enables mobile push notifications
for PCA, rather than text notifications.
'
description: The user profile object, storing collected info about the user.
description: ''
'403':
description: Access denied (missing or improper authentication).
tags:
- '[Accounts] User'
patch:
operationId: Partial Update User
description: '(PATCH `/accounts/me/`)
This view exposes the Penn Labs Accounts User object.
<span style="color:red;">User authentication required</span>.'
parameters: []
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
readOnly: true
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
first_name:
type: string
maxLength: 150
last_name:
type: string
maxLength: 150
profile:
type: object
properties:
email:
type: string
format: email
nullable: true
description: The email of the User. Defaults to null.
maxLength: 254
phone:
type: string
nullable: true
description: '
The phone number of the user. Defaults to null.
The phone number will be stored in the E164 format, but any form parseable by
the
[phonenumbers library](https://pypi.org/project/phonenumbers/)
will be accepted and converted to E164 format automatically upon saving.
'
maxLength: 100
push_notifications:
type: boolean
description: '
Defaults to False, changed to True if the User enables mobile push notifications
for PCA, rather than text notifications.
'
description: The user profile object, storing collected info about the user.
responses:
'200':
content:
application/json:
schema:
type: object
properties:
username:
type: string
readOnly: true
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
first_name:
type: string
maxLength: 150
last_name:
type: string
maxLength: 150
profile:
type: object
properties:
email:
type: string
format: email
nullable: true
description: The email of the User. Defaults to null.
maxLength: 254
phone:
type: string
nullable: true
description: '
The phone number of the user. Defaults to null.
The phone number will be stored in the E164 format, but any form parseable by
the
[phonenumbers library](https://pypi.org/project/phonenumbers/)
will be accepted and converted to E164 format automatically upon saving.
'
maxLength: 100
push_notifications:
type: boolean
description: '
Defaults to False, changed to True if the User enables mobile push notifications
for PCA, rather than text notifications.
'
description: The user profile object, storing collected info about the user.
description: ''
'403':
description: Access denied (missing or improper authentication).
tags:
- '[Accounts] User'
/api/review/course/{course_code}:
get:
operationId: Retrieve Course Reviews
description: '(GET `/api/review/course/{course_code}`)
<span style="color:red;">User authentication required</span>.'
parameters:
- name: course_code
in: path
required: true
description: The dash-joined department and code of the course you want reviews for, e.g. `CIS-120`
for CIS-120.
schema:
type: string
- name: semester
in: query
description: Optionally specify the semester of the desired course (defaults to most recent course
with the specified course code).
schema:
type: string
required: false
responses:
'200':
content:
application/json:
schema:
properties:
code:
type: string
description: The dash-joined department and most-recent code of this course, e.g.
`CIS-1200`.
last_offered_sem_if_superceded:
type: string
description: The last semester in which this course was offered, if it has been superseded
by a more recent course (with the same full code).
aliases:
type: array
description: A list of courses that are crosslisted with this course (each represented
by its dash-joined department and code).
items:
type: string
historical_codes:
description: The historical lineage of primary course codes that have represented
this course (from most recent to oldest).
items:
type: object
properties:
full_code:
type: string
description: The dash-joined department and course code.
branched_from:
type: boolean
description: A flag indicating whether this code was branched into multiple
new codes (e.g. in fall 2022). In these cases we should link to the old course
on PCR because its reviews will not be included on the same page (unlike linear
links).
semester:
type: string
description: The most recent semester this code was used (of the form YYYYx
where x is A [for spring], B [summer], or C [fall]), e.g. `2022C` for fall
2022.
name:
type: string
description: The title of the course, e.g. 'Programming Languages and Techniques I'
for CIS-120.
description:
type: string
description: The description of the course, e.g. 'A fast-paced introduction to the
fundamental concepts of programming... [etc.]' for CIS-120.
latest_semester:
type: string
description: The most recent semester this course was offered (of the form YYYYx where
x is A [for spring], B [summer], or C [fall]), e.g. `2022C` for fall 2022.
registration_metrics:
type: boolean
description: True if this course has registration metrics that you can access via
the Retrieve Plots route.
num_sections:
type: integer
description: The number of sections belonging to this course (excluding non-primary
crosslisted sections) across all semesters (that we have data for).
num_sections_recent:
type: integer
description: The number of sections belonging to this course (excluding non-primary
crosslisted sections) in its most recent semester.
average_reviews:
type: object
description: This course's average reviews across all of its sections (excluding non-primary
crosslisted sections) from all semesters. Note that if any of these subfields are
missing or null, that means the subfield is not applicable or missing from our data
(you should check for null values).
properties:
rSemesterCalc:
type: string
description: The oldest semester included in these review aggregations (of the
form YYYYx where x is A [for spring], B [summer], or C [fall]), e.g. `2019C`
for fall 2019. This field will not be missing.
rSemesterCount:
type: integer
description: The number of semesters included in these review aggregations. This
field will not be missing.
rInstructorQuality:
type: number
description: Average Instructor Quality
rCourseQuality:
type: number
description: Average Course Quality
rCommunicationAbility:
type: number
description: Average Comm. Ability
rStimulateInterest:
type: number
description: Average Stimulate Ability
rInstructorAccess:
type: number
description: Average Instructor Access
rDifficulty:
type: number
description: Average Difficulty
rWorkRequired:
type: number
description: Average Work Required
rTaQuality:
type: number
description: Average TA Quality
rReadingsValue:
type: number
description: Average Readings Value
rAmountLearned:
type: number
description: Average Amount Learned
rRecommendMajor:
type: number
description: Average Recommend Major
rRecommendNonmajor:
type: number
description: Average Recommend Non-Major
rAbilitiesChallenged:
type: number
description: Average Abilities Challenged
rClassPace:
type: number
description: Average Class Pace
rInstructorEffective:
type: number
description: Average Instructor Effectiveness
rNativeAbility:
type: number
description: Average Native Ability
rFinalEnrollment:
type: number
description: Average Final Enrollment at the End of the Semester
rPercentOpen:
type: number
description: Average Percent of Add/Drop Period Open
rNumOpenings:
type: number
description: Average Number of Openings During Add/Drop
rFilledInAdvReg:
type: number
description: Average Percent of Sections Completely Filled During Advance Registration
recent_reviews:
type: object
description: This course's average reviews across all of its sections (excluding non-primary
crosslisted sections) from the most recent semester. Note that if any of these subfields
are missing or null, that means the subfield is not applicable or missing from our
data (you should check for null values).
properties:
rSemesterCalc:
type: string
description: The oldest semester included in these review aggregations (of the
form YYYYx where x is A [for spring], B [summer], or C [fall]), e.g. `2019C`
for fall 2019. This field will not be missing.
rSemesterCount:
type: integer
description: The number of semesters included in these review aggregations. This
field will not be missing.
rInstructorQuality:
type: number
description: Average Instructor Quality
rCourseQuality:
type: number
description: Average Course Quality
rCommunicationAbility:
type: number
description: Average Comm. Ability
rStimulateInterest:
type: number
description: Average Stimulate Ability
rInstructorAccess:
type: number
description: Average Instructor Access
rDifficulty:
type: number
description: Average Difficulty
rWorkRequired:
type: number
description: Average Work Required
rTaQuality:
type: number
description: Average TA Quality
rReadingsValue:
type: number
description: Average Readings Value
rAmountLearned:
type: number
description: Average Amount Learned
rRecommendMajor:
type: number
description: Average Recommend Major
rRecommendNonmajor:
type: number
description: Average Recommend Non-Major
rAbilitiesChallenged:
type: number
description: Average Abilities Challenged
rClassPace:
type: number
description: Average Class Pace
rInstructorEffective:
type: number
description: Average Instructor Effectiveness
rNativeAbility:
type: number
description: Average Native Ability
rFinalEnrollment:
type: number
description: Average Final Enrollment at the End of the Semester
rPercentOpen:
type: number
description: Average Percent of Add/Drop Period Open
rNumOpenings:
type: number
description: Average Number of Openings During Add/Drop
rFilledInAdvReg:
type: number
description: Average Percent of Sections Completely Filled During Advance Registration
num_semesters:
type: integer
description: The number of semesters for which this course has been taught (that we
have data for).
instructors:
type: object
description: Reviews for this course broken down by instructor. Note that each key
in this subdictionary is a stringified instructor id (indicated by `STRINGIFIED_INSTRUCTOR_ID`;
this is not an actual key but a placeholder for potentially many keys).
properties:
STRINGIFIED_INSTRUCTOR_ID:
type: object
description: This key `STRINGIFIED_INSTRUCTOR_ID` is a placeholder for potentially
many stringified instructor id keys.
properties:
id:
type: integer
description: The integer id of this instructor; note that this is just the
int version of this subdictionary's key in the parent dictionary.
average_reviews:
type: object
description: This instructor's average reviews across all of the sections
of this course that he/she has taught. Note that if any of these subfields
are missing or null, that means the subfield is not applicable or missing
from our data (you should check for null values).
properties:
rInstructorQuality:
type: number
description: Average Instructor Quality
rCourseQuality:
type: number
description: Average Course Quality
rCommunicationAbility:
type: number
description: Average Comm. Ability
rStimulateInterest:
type: number
description: Average Stimulate Ability
rInstructorAccess:
type: number
description: Average Instructor Access
rDifficulty:
type: number
description: Average Difficulty
rWorkRequired:
type: number
description: Average Work Required
rTaQuality:
type: number
description: Average TA Quality
rReadingsValue:
type: number
description: Average Readings Value
rAmountLearned:
type: number
description: Average Amount Learned
rRecommendMajor:
type: number
description: Average Recommend Major
rRecommendNonmajor:
type: number
description: Average Recommend Non-Major
rAbilitiesChallenged:
type: number
description: Average Abilities Challenged
rClassPace:
type: number
description: Average Class Pace
rInstructorEffective:
type: number
description: Average Instructor Effectiveness
rNativeAbility:
type: number
description: Average Native Ability
rFinalEnrollment:
type: number
description: Average Final Enrollment at the End of the Semester
rPercentOpen:
type: number
description: Average Percent of Add/Drop Period Open
rNumOpenings:
type: number
description: Average Number of Openings During Add/Drop
rFilledInAdvReg:
type: number
description: Average Percent of Sections Completely Filled During Advance
Registration
recent_reviews:
type: object
description: This instructor's average reviews across all of the sections
of this course that he/she has taught in his/her most recent semester teaching
this course that has review data. Note that if any of these subfields are
missing or null, that means the subfield is not applicable or missing from
our data (you should check for null values).
properties:
rInstructorQuality:
type: number
description: Average Instructor Quality
rCourseQuality:
type: number
description: Average Course Quality
rCommunicationAbility:
type: number
description: Average Comm. Ability
rStimulateInterest:
type: number
description: Average Stimulate Ability
rInstructorA
# --- truncated at 32 KB (359 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-pennsylvania/refs/heads/main/openapi/university-of-pennsylvania-penn-courses.yaml