openapi: 3.0.2
info:
title: Penn Courses API Documentation [Accounts] User [Accounts] User [PDP] Fulfillment 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: '[PDP] Fulfillment'
description: ''
paths:
/api/degree/degreeplans/{degreeplan_pk}/fulfillments:
get:
operationId: List Fulfillments
description: '(GET `/api/degree/degreeplans/{degreeplan_pk}/fulfillments`)
List, retrieve, create, destroy, and update a Fulfillment.'
parameters:
- name: degreeplan_pk
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
description: ''
tags:
- '[PDP] Fulfillment'
post:
operationId: Create Fulfillment
description: '(POST `/api/degree/degreeplans/{degreeplan_pk}/fulfillments`)
Create or update fulfillment.'
parameters:
- name: degreeplan_pk
in: path
required: true
description: ''
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
required:
- degree_plan
- full_code
responses:
'201':
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
description: ''
tags:
- '[PDP] Fulfillment'
/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}:
get:
operationId: Retrieve Fulfillment
description: '(GET `/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}`)
List, retrieve, create, destroy, and update a Fulfillment.'
parameters:
- name: degreeplan_pk
in: path
required: true
description: ''
schema:
type: string
- name: full_code
in: path
required: true
description: The dash-joined department and code of the course, e.g., `CIS-120`
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
description: ''
tags:
- '[PDP] Fulfillment'
delete:
operationId: Destroy Fulfillment
description: '(DELETE `/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}`)
List, retrieve, create, destroy, and update a Fulfillment.'
parameters:
- name: degreeplan_pk
in: path
required: true
description: ''
schema:
type: string
- name: full_code
in: path
required: true
description: The dash-joined department and code of the course, e.g., `CIS-120`
schema:
type: string
responses:
'204':
description: ''
tags:
- '[PDP] Fulfillment'
/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}/override:
post:
operationId: Add Override Fulfillment
description: '(POST `/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}/override`)
Add a manual override that allows a course to count for a rule regardless of whether
it satisfies the rule''s Q filter. Also adds the rule to the fulfillment''s selected
rules if not already present.
POST with `{"rule_id": <id>}`.'
parameters:
- name: degreeplan_pk
in: path
required: true
description: ''
schema:
type: string
- name: full_code
in: path
required: true
description: The dash-joined department and code of the course, e.g., `CIS-120`
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
required:
- degree_plan
- full_code
responses:
'201':
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
description: ''
tags:
- '[PDP] Fulfillment'
/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}/switch-rule:
post:
operationId: Switch Rule Fulfillment
description: '(POST `/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}/switch-rule`)
Switch a fulfillment''s selected rule to another rule in the same degree.
This promotes the requested rule from `unselected_rules` to `rules`, and
demotes any currently selected rules for that same degree into
`unselected_rules`.
If another course was already fulfilling the target rule, that course is'
parameters:
- name: degreeplan_pk
in: path
required: true
description: ''
schema:
type: string
- name: full_code
in: path
required: true
description: The dash-joined department and code of the course, e.g., `CIS-120`
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
required:
- degree_plan
- full_code
responses:
'201':
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
degree_plan:
type: integer
description: The degree plan with which this fulfillment is associated
full_code:
type: string
description: The dash-joined department and code of the course, e.g., `CIS-120`
maxLength: 16
course:
type: string
readOnly: true
semester:
type: string
nullable: 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. Null if this fulfillment
does not yet have a semester.
'
maxLength: 5
rules:
type: array
items:
type: integer
unselected_rules:
type: array
items:
type: integer
description: '
The rules this course fulfills that should be shown in the open-ended rule box
(as opposed to the expandable box). Blank if this course should not be included in
any open-ended rule boxes.
'
legal:
type: boolean
description: '
True if course associated with this fulfillment isn''t illegally double counted anywhere,
false otherwise.
'
overrides:
type: array
items:
type: string
readOnly: true
description: ''
tags:
- '[PDP] Fulfillment'
/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}/override/{rule_id}:
delete:
operationId: Remove Override Fulfillment
description: '(DELETE `/api/degree/degreeplans/{degreeplan_pk}/fulfillments/{full_code}/override/{rule_id}`)
Remove a manual override, and remove the rule from the fulfillment''s selected
and unselected rules.
DELETE to `override/<rule_id>/`.'
parameters:
- name: degreeplan_pk
in: path
required: true
description: ''
schema:
type: string
- name: full_code
in: path
required: true
description: The dash-joined department and code of the course, e.g., `CIS-120`
schema:
type: string
- name: rule_id
in: path
required: true
description: ''
schema:
type: string
responses:
'204':
description: ''
tags:
- '[PDP] Fulfillment'
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'