openapi: 3.0.2
info:
title: Penn Courses API Documentation [Accounts] User [Accounts] User [PCx] Section API
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: contact@pennlabs.org
servers:
- url: https://penncoursereview.com
description: Penn Course Review
- url: https://penncourseplan.com
description: Penn Course Plan
tags:
- name: '[PCx] Section'
description: ''
paths:
/api/base/{semester}/search/sections/:
get:
operationId: Section Search
description: '(GET `/api/base/{semester}/search/sections/`)
Retrieve a list of sections (less detailed than [PCx] Section, or SectionDetail on the
backend). The sections are filtered by the search term (assumed to be a prefix of a
section''s full code, with each chunk either space-delimited, dash-delimited, or not delimited).'
parameters:
- name: semester
in: path
required: true
description: 'The semester of the course (of the form YYYYx where x is A [for spring], B [summer], or C [fall]), e.g. ''2019C'' for fall 2019. Alternatively, you can just pass ''current'' for the current semester. Finally, you can pass ''all'' to always return the most recent course for each full_code, no matter which semester it is from. The ''all'' option can be significantly more expensive, so use only where needed. '
schema:
type: string
- name: search
required: false
in: query
description: A search term.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
type: object
properties:
section_id:
type: string
readOnly: true
description: '
The dash-separated dept, full-code, and section-code, e.g. `CIS-120-001` for the
001 lecture section of CIS-120.
'
status:
enum:
- O
- C
- X
- ''
type: string
readOnly: true
description: 'The registration status of the section. Options and meanings: <table width=100%><tr><td>"O"</td><td>"Open"</td></tr><tr><td>"C"</td><td>"Closed"</td></tr><tr><td>"X"</td><td>"Cancelled"</td></tr><tr><td>""</td><td>"Unlisted"</td></tr></table>'
activity:
enum:
- ''
- CLN
- CRT
- DAB
- DIS
- DPC
- FLD
- HYB
- IND
- LAB
- LEC
- MST
- ONL
- PRC
- REC
- SEM
- SRT
- STU
type: string
readOnly: true
description: 'The section activity, e.g. `LEC` for CIS-120-001 (2020A). Options and meanings: <table width=100%><tr><td>""</td><td>"Undefined"</td></tr><tr><td>"CLN"</td><td>"Clinic"</td></tr><tr><td>"CRT"</td><td>"Clinical Rotation"</td></tr><tr><td>"DAB"</td><td>"Dissertation Abroad"</td></tr><tr><td>"DIS"</td><td>"Dissertation"</td></tr><tr><td>"DPC"</td><td>"Doctoral Program Exchange"</td></tr><tr><td>"FLD"</td><td>"Field Work"</td></tr><tr><td>"HYB"</td><td>"Hybrid"</td></tr><tr><td>"IND"</td><td>"Independent Study"</td></tr><tr><td>"LAB"</td><td>"Lab"</td></tr><tr><td>"LEC"</td><td>"Lecture"</td></tr><tr><td>"MST"</td><td>"Masters Thesis"</td></tr><tr><td>"ONL"</td><td>"Online"</td></tr><tr><td>"PRC"</td><td>"Practicum"</td></tr><tr><td>"REC"</td><td>"Recitation"</td></tr><tr><td>"SEM"</td><td>"Seminar"</td></tr><tr><td>"SRT"</td><td>"Senior Thesis"</td></tr><tr><td>"STU"</td><td>"Studio"</td></tr></table>'
meeting_times:
type: string
readOnly: true
description: '
A JSON-stringified list of meeting times of the form
`{days code} {start time} - {end time}`, e.g.
`["MWF 09:00 AM - 10:00 AM","F 11:00 AM - 12:00 PM","T 05:00 PM - 06:00 PM"]` for
PHYS-151-001 (2020A). Each letter of the days code is of the form M, T, W, R, F for each
day of the work week, respectively (and multiple days are combined with concatenation).
To access the Meeting objects for this section, the related field `meetings` can be used.
'
instructors:
type: array
items: []
readOnly: true
description: A list of the names of the instructors teaching this section.
course_code:
type: string
readOnly: true
description: '
The full code of the course this section belongs to, e.g. `CIS-120` for CIS-120-001.
'
course_title:
type: string
readOnly: true
description: '
The title of the course this section belongs to, e.g.
''Programming Languages and Techniques I'' for CIS-120-001.
'
semester:
type: string
readOnly: true
description: '
The semester of the course (of the form YYYYx where x is A [for spring],
B [summer], or C [fall]), e.g. `2019C` for fall 2019.
'
registration_volume:
type: integer
readOnly: true
description: The number of active PCA registrations watching this section.
description: Sections Listed Successfully.
tags:
- '[PCx] Section'
/api/base/{semester}/sections/{full_code}/:
get:
operationId: Retrieve Section
description: '(GET `/api/base/{semester}/sections/{full_code}/`)
Retrieve a detailed look at a specific course section.'
parameters:
- name: semester
in: path
required: true
description: 'The semester of the course (of the form YYYYx where x is A [for spring], B [summer], or C [fall]), e.g. ''2019C'' for fall 2019. Alternatively, you can just pass ''current'' for the current semester. Finally, you can pass ''all'' to always return the most recent course for each full_code, no matter which semester it is from. The ''all'' option can be significantly more expensive, so use only where needed. '
schema:
type: string
- name: full_code
in: path
required: true
description: '
The full code of the section, in the form ''{dept code}-{course code}-{section code}'',
e.g. `CIS-120-001` for the 001 section of CIS-120.
'
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id:
type: string
readOnly: true
description: '
The dash-separated dept, full-code, and section-code, e.g. `CIS-120-001` for the
001 lecture section of CIS-120.
'
status:
enum:
- O
- C
- X
- ''
type: string
readOnly: true
description: 'The registration status of the section. Options and meanings: <table width=100%><tr><td>"O"</td><td>"Open"</td></tr><tr><td>"C"</td><td>"Closed"</td></tr><tr><td>"X"</td><td>"Cancelled"</td></tr><tr><td>""</td><td>"Unlisted"</td></tr></table>'
activity:
enum:
- ''
- CLN
- CRT
- DAB
- DIS
- DPC
- FLD
- HYB
- IND
- LAB
- LEC
- MST
- ONL
- PRC
- REC
- SEM
- SRT
- STU
type: string
readOnly: true
description: 'The section activity, e.g. `LEC` for CIS-120-001 (2020A). Options and meanings: <table width=100%><tr><td>""</td><td>"Undefined"</td></tr><tr><td>"CLN"</td><td>"Clinic"</td></tr><tr><td>"CRT"</td><td>"Clinical Rotation"</td></tr><tr><td>"DAB"</td><td>"Dissertation Abroad"</td></tr><tr><td>"DIS"</td><td>"Dissertation"</td></tr><tr><td>"DPC"</td><td>"Doctoral Program Exchange"</td></tr><tr><td>"FLD"</td><td>"Field Work"</td></tr><tr><td>"HYB"</td><td>"Hybrid"</td></tr><tr><td>"IND"</td><td>"Independent Study"</td></tr><tr><td>"LAB"</td><td>"Lab"</td></tr><tr><td>"LEC"</td><td>"Lecture"</td></tr><tr><td>"MST"</td><td>"Masters Thesis"</td></tr><tr><td>"ONL"</td><td>"Online"</td></tr><tr><td>"PRC"</td><td>"Practicum"</td></tr><tr><td>"REC"</td><td>"Recitation"</td></tr><tr><td>"SEM"</td><td>"Seminar"</td></tr><tr><td>"SRT"</td><td>"Senior Thesis"</td></tr><tr><td>"STU"</td><td>"Studio"</td></tr></table>'
credits:
type: number
multipleOf: 0.01
maximum: 100
minimum: -100
readOnly: true
nullable: true
description: The number of credits this section is worth.
capacity:
type: integer
readOnly: true
description: The max allowed enrollment across all crosslistings of this section.
semester:
type: string
readOnly: true
description: '
The semester of the course (of the form YYYYx where x is A [for spring],
B [summer], or C [fall]), e.g. `2019C` for fall 2019.
'
meetings:
type: string
readOnly: true
description: '
A list of the meetings of this section (each meeting is a continuous span of time
during which a section would meet).
'
instructors:
type: array
items: []
readOnly: true
description: A list of the names of the instructors teaching this section.
course_quality:
type: number
multipleOf: 0.001
maximum: 10
minimum: -10
readOnly: true
description: The average course quality rating for this section, on a scale of 0-4.
instructor_quality:
type: number
multipleOf: 0.001
maximum: 10
minimum: -10
readOnly: true
description: The average instructor quality for this section, on a scale of 0-4.
difficulty:
type: number
multipleOf: 0.001
maximum: 10
minimum: -10
readOnly: true
description: The average difficult rating for this section, on a scale of 0-4.
work_required:
type: number
multipleOf: 0.001
maximum: 10
minimum: -10
readOnly: true
description: The average work required for this section, on a scale of 0-4.
associated_sections:
type: array
items: []
readOnly: true
description: '
A list of all sections associated with the Course which this section belongs to; e.g. for
CIS-120-001, all of the lecture and recitation sections for CIS-120 (including CIS-120-001)
in the same semester.
'
registration_volume:
type: integer
readOnly: true
description: The number of active PCA registrations watching this section.
description: Section detail retrieved successfully.
tags:
- '[PCx] Section'
x-tagGroups:
- name: Penn Course Plan
tags:
- '[PCP] Course Recommendations'
- '[PCP] Schedule'
- '[PCP] Primary Schedule'
- '[PCP] Calendar'
- '[PCP] Break'
- name: Penn Course Alert
tags:
- '[PCA] Registration History'
- '[PCA] Registration'
- name: Penn Course Review
tags:
- '[PCR] Course Reviews'
- '[PCR] Autocomplete Dump'
- '[PCR] Department Reviews'
- '[PCR] Section-Specific Reviews'
- '[PCR] Plots'
- '[PCR] Instructor Reviews'
- name: Penn Courses (Base)
tags:
- '[PCx] NGSS Restrictions'
- '[PCx] Attributes'
- '[PCx] Status Updates'
- '[PCx] Healths'
- '[PCx] Friendship'
- '[PCx] Course'
- '[PCx] Section'
- '[PCx] Pre-NGSS Requirements'
- name: Penn Labs Accounts
tags:
- '[Accounts] User'
- name: Other
tags:
- '[PDP] Docked Course'
- '[PDP] Degree'
- '[PDP] Onboard From Transcript'
- '[PDP] Fulfillment'
- '[PDP] Degree Plan Lists'
- '[PDP] Satisfied Rule Lists'
- '[PDP] Degree Plan Detail'