openapi: 3.0.2
info:
title: Penn Courses API Documentation [Accounts] User [Accounts] User [PCP] Schedule 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: '[PCP] Schedule'
description: '
These routes allow interfacing with the user''s PCP Schedules for the current semester,
stored on the backend. Ever since we integrated Penn Labs Accounts into PCP so that users
can store their schedules across devices and browsers, we have stored users'' schedules on
our backend (rather than local storage).
'
paths:
/api/plan/schedules/:
get:
operationId: List Schedules
description: '(GET `/api/plan/schedules/`)
Get a list of all the logged-in user''s schedules for the current semester. Normally, the
response code is 200. Each object in the returned list is of the same form as the object
returned by Retrieve Schedule.
<span style="color:red;">User authentication required</span>.'
parameters: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
description: The id of the schedule.
sections:
type: array
items: []
description: The sections in the schedule.
breaks:
type: array
items: []
description: The breaks in the schedule.
semester:
type: string
description: '
The academic semester planned out by the schedule (of the form YYYYx where x is A
[for spring], B [summer], or C [fall]), e.g. `2019C` for fall 2019.
'
maxLength: 5
name:
type: string
description: '
The user''s nick-name for the schedule. No two schedules can match in all of the fields
`[name, semester, person]`
'
maxLength: 255
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
description: Schedules listed successfully.
'403':
description: Access denied (missing or improper authentication).
tags:
- '[PCP] Schedule'
post:
operationId: Create Schedule
description: '(POST `/api/plan/schedules/`)
Use this route to create a schedule for the authenticated user.
This route will return a 201 if it succeeds (or a 200 if the POST specifies an id which already
is associated with a schedule, causing that schedule to be updated), with a JSON in the same
format as if you were to get the schedule you just posted (the 200 response schema for Retrieve
Schedule). If any of the given sections are invalid, a 404 is returned. If any two sections
in the `sections` list have differing semesters, a 400 is returned.
Note that your posted object can include either a `sections` field or a `meetings` field to
list all sections you would like to be in the schedule (mentioned above).
If both fields exist in the object, only `meetings` will be considered. In all cases,
the field in question will be renamed to `sections`, so that will be the field name whenever
you GET from the server. (Sorry for this confusing behavior, it is grandfathered in
from when the PCP frontend was referring to sections as meetings, before schedules were
stored on the backend.)
<span style="color:red;">User authentication required</span>.'
parameters: []
requestBody:
content:
application/json:
schema:
type: object
required:
- sections
- name
properties:
id:
required: false
type: string
description: '
Optionally include an `id` to update the schedule
with the given id (if such a schedule exists),
or otherwise create a new schedule with that id.
'
semester:
type: string
description: '
The semester of the schedule (of the form YYYYx where x is
A [for spring], B [summer], or C [fall]), e.g. 2019C for fall 2019.
Can also be specified in Path format (YYYYxx, where xx is
10 [for spring], 20 [summer], or 30 [fall]), e.g. 201930 for fall 2019.
You can omit this field and the first semester found in the
sections/meetings list will be used instead (or if no semester
is specified in the request, the current semester open for registration
will be used).
'
sections:
type: array
description: The sections in the schedule (can also be called "meetings").
items:
type: object
required:
- id
properties:
id:
type: string
description: A course code of the form DEPT-XXXX (e.g. CIS-1200), or a Path CRN
semester:
type: string
description: '
Optionally specify a section semester if you want the
backend to validate that all sections have the same
semester as the claimed schedule semester (taking the
first section semester as the schedule semester if none
is specified). Format is same as schedule semester.
'
name:
type: string
maxLength: 255
description: The user's nick-name for the schedule. No two schedules can match in all of the fields [name, semester, person]. Optional for PUT path registration.
responses:
'201':
description: Schedule successfully created.
'403':
description: Access denied (missing or improper authentication).
'200':
description: Schedule successfully updated (a schedule with the specified id already existed).
'400':
description: Bad request (see description above).
tags:
- '[PCP] Schedule'
/api/plan/schedules/{id}/:
get:
operationId: Retrieve Schedule
description: '(GET `/api/plan/schedules/{id}/`)
Get one of the logged-in user''s schedules for the current semester, using the schedule''s ID.
If a schedule with the specified ID exists, a 200 response code is returned, along with
the schedule object.
If the given id does not exist, a 404 is returned.
<span style="color:red;">User authentication required</span>.'
parameters:
- name: id
in: path
required: true
description: A unique integer value identifying this schedule.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The id of the schedule.
sections:
type: array
items: []
description: The sections in the schedule.
breaks:
type: array
items: []
description: The breaks in the schedule.
semester:
type: string
description: '
The academic semester planned out by the schedule (of the form YYYYx where x is A
[for spring], B [summer], or C [fall]), e.g. `2019C` for fall 2019.
'
maxLength: 5
name:
type: string
description: '
The user''s nick-name for the schedule. No two schedules can match in all of the fields
`[name, semester, person]`
'
maxLength: 255
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
description: Successful retrieve (the specified schedule exists).
'403':
description: Access denied (missing or improper authentication).
'404':
description: No schedule with the specified id exists.
tags:
- '[PCP] Schedule'
put:
operationId: Update Schedule
description: '(PUT `/api/plan/schedules/{id}/`)
Send a put request to this route to update a specific schedule.
The `id` path parameter (an integer) specifies which schedule you want to update. [You can also
pass `path` for the `id` path parameter, in order to create/update a Path Registration schedule
for the user. But to do this, you must be authenticated via Platform''s token auth for IPC,
e.g. from Penn Mobile - otherwise a 403 is returned.] If a schedule with
the specified id does not exist, a 404 is returned. In the body of the PUT, use the same format
as a POST request (see the Create Schedule docs).
This is an alternate way to update schedules (you can also just include the id field
in a schedule when you post and it will update that schedule if the id exists). Note that in a
put request the id field in the putted object is ignored; the id taken from the route
always takes precedence. If the request succeeds, it will return a 200 and a JSON in the same
format as if you were to get the schedule you just updated (in the same format as returned by
the GET /schedules/ route).
<span style="color:red;">User authentication required</span>.'
parameters:
- name: id
in: path
required: true
description: A unique integer value identifying this schedule.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- sections
- name
properties:
semester:
type: string
description: '
The semester of the schedule (of the form YYYYx where x is
A [for spring], B [summer], or C [fall]), e.g. 2019C for fall 2019.
Can also be specified in Path format (YYYYxx, where xx is
10 [for spring], 20 [summer], or 30 [fall]), e.g. 201930 for fall 2019.
You can omit this field and the first semester found in the
sections/meetings list will be used instead (or if no semester
is specified in the request, the current semester open for registration
will be used).
'
sections:
type: array
description: The sections in the schedule (can also be called "meetings").
items:
type: object
required:
- id
properties:
id:
type: string
description: A course code of the form DEPT-XXXX (e.g. CIS-1200), or a Path CRN
semester:
type: string
description: '
Optionally specify a section semester if you want the
backend to validate that all sections have the same
semester as the claimed schedule semester (taking the
first section semester as the schedule semester if none
is specified). Format is same as schedule semester.
'
name:
type: string
maxLength: 255
description: The user's nick-name for the schedule. No two schedules can match in all of the fields [name, semester, person]. Optional for PUT path registration.
responses:
'200':
description: Successful update (the specified schedule was found and updated).
'403':
description: Access denied (missing or improper authentication).
'400':
description: Bad request (see description above).
'404':
description: No schedule with the specified id exists.
tags:
- '[PCP] Schedule'
delete:
operationId: Destroy Schedule
description: '(DELETE `/api/plan/schedules/{id}/`)
Send a delete request to this route to delete a specific schedule. The `id` path parameter
(an integer) specifies which schedule you want to update. If a schedule with the specified
id does not exist, a 404 is returned. If the delete is successful, a 204 is returned.
<span style="color:red;">User authentication required</span>.'
parameters:
- name: id
in: path
required: true
description: A unique integer value identifying this schedule.
schema:
type: string
responses:
'204':
description: Successful delete (the specified schedule was found and deleted).
'403':
description: Access denied (missing or improper authentication).
'404':
description: No schedule with the specified id exists.
tags:
- '[PCP] Schedule'
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'