openapi: 3.0.2
info:
title: Penn Courses API Documentation [Accounts] User [Accounts] User [PCA] Registration History 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: '[PCA] Registration History'
description: '
These routes expose a user''s registration history (including
inactive and obsolete registrations) for the current semester. Inactive registrations are
registrations which would not trigger a notification to be sent if their section opened,
and obsolete registrations are registrations which are not at the head of their resubscribe
chain.
'
paths:
/api/alert/registrationhistory/:
get:
operationId: List Registration History
description: '(GET `/api/alert/registrationhistory/`)
List all of the user''s registrations for the current semester, regardless of whether
they are active, obsolete (not at the head of their resubscribe chains), or deleted. Note
that this is not appropriate to use for listing registrations and presenting them to the user;
for that you should use List Registrations (GET `/api/alert/registrations/`).
User authentication required.'
parameters: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
readOnly: true
created_at:
type: string
format: date-time
readOnly: true
description: The datetime at which this registration was created.
original_created_at:
type: string
format: date-time
readOnly: true
nullable: true
description: '
The datetime at which the tail of the resubscribe chain to which this registration belongs
was created. In other words, the datetime at which the user created the original
registration for this section, before resubscribing some number of times
(0 or more) to reach this registration.
'
updated_at:
type: string
format: date-time
readOnly: true
description: The datetime at which this registration was last modified.
section:
type: string
description: The dash-separated full code of the section associated with this Registration.
user:
type: string
readOnly: true
description: The Penn Labs Accounts username of the User who owns this Registration.
cancelled:
type: boolean
readOnly: true
description: '
Defaults to False, changed to True if the registration has been cancelled. A cancelled
registration will not trigger any alerts to be sent even if the relevant section opens.
A cancelled section can be resubscribed to (unlike deleted alerts), and will show up
on the manage alerts page on the frontend (also unlike deleted alerts). Note that once
a registration is cancelled, it cannot be uncancelled (resubscribing creates a new
registration which is accessible via the resubscribed_to field, related name of
resubscribed_from).
'
cancelled_at:
type: string
format: date-time
readOnly: true
nullable: true
description: When was the registration cancelled? Null if it hasn't been cancelled.
deleted:
type: boolean
readOnly: true
description: '
Defaults to False, changed to True if the registration has been deleted. A deleted
registration will not trigger any alerts to be sent even if the relevant section opens.
A deleted section cannot be resubscribed to or undeleted, and will not show up on the
manage alerts page on the frontend. It is kept in the database for analytics purposes,
even though it serves no immediate functional purpose for its original user.
'
deleted_at:
type: string
format: date-time
readOnly: true
nullable: true
description: When was the registration deleted? Null if it hasn't been deleted.
auto_resubscribe:
type: boolean
readOnly: true
description: '
Defaults to False, in which case a registration will not be automatically resubscribed
after it triggers an alert to be sent (but the user can still resubscribe to a sent alert,
as long as it is not deleted). If set to True, the registration will be automatically
resubscribed to once it triggers an alert to be sent (this is useful in the case of
volatile sections which are opening and closing frequently, often before the user has
time to register).
'
notification_sent:
type: boolean
readOnly: true
description: True if an alert has been sent to the user, false otherwise.
notification_sent_at:
type: string
format: date-time
readOnly: true
nullable: true
description: '
When was an alert sent to the user as a result of this registration?
Null if an alert was not sent.
'
last_notification_sent_at:
type: string
readOnly: true
description: '
The last time the user was sent an opening notification for this registration''s
section. This property is None (or null in JSON) if no notification has been sent to the
user for this registration''s section.
This is used on the frontend to tell the user a last time an alert was sent for
the SECTION of a certain registration in the manage alerts page. Since the idea of
Registration objects and resubscribe chains is completely abstracted out of the User''s
understanding, they expect alerts to work by section (so the "LAST NOTIFIED"
column should tell them the last time they were alerted about that section).
'
close_notification:
type: boolean
readOnly: true
description: "Defaults to false. If set to true, the user will receive\n a close notification (an alert when the section closes after an\n alert was sent for it opening).\n"
close_notification_sent:
type: boolean
readOnly: true
description: True if a close notification has been sent to the user, false otherwise.
close_notification_sent_at:
type: string
format: date-time
readOnly: true
nullable: true
description: '
When was a close notification sent to the user as a result of this registration?
Null if a close notification was not sent.
'
is_active:
type: string
readOnly: true
description: '
True if the registration would send an alert when the watched section changes to open,
False otherwise. This is equivalent to
[not(notification_sent or deleted or cancelled) and semester is current].
'
is_waiting_for_close:
type: string
readOnly: true
description: '
True if the registration is waiting to send a close notification to the user
once the section closes. False otherwise.
'
section_status:
type: string
readOnly: true
description: 'The current status of the watched section. Options and meanings: | "O" | "Open" |
| "C" | "Closed" |
| "X" | "Cancelled" |
| "" | "Unlisted" |
'
description: Registration history successfully listed.
'403':
description: Access denied (missing or improper authentication).
tags:
- '[PCA] Registration History'
/api/alert/registrationhistory/{id}/:
get:
operationId: Retrieve Historic Registration
description: '(GET `/api/alert/registrationhistory/{id}/`)
Get the detail of a specific registration from the current semester. All registrations are
accessible via this endpoint, regardless of whether they are active,
obsolete (not at the head of their resubscribe chains), or deleted. Unless you need to access
inactive and obsolete registrations, you should probably use Retrieve Registration
(GET `/api/alert/registrations/{id}/`) rather than this endpoint.
User authentication required.'
parameters:
- name: id
in: path
required: true
description: A unique integer value identifying this registration.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id:
type: integer
readOnly: true
created_at:
type: string
format: date-time
readOnly: true
description: The datetime at which this registration was created.
original_created_at:
type: string
format: date-time
readOnly: true
nullable: true
description: '
The datetime at which the tail of the resubscribe chain to which this registration belongs
was created. In other words, the datetime at which the user created the original
registration for this section, before resubscribing some number of times
(0 or more) to reach this registration.
'
updated_at:
type: string
format: date-time
readOnly: true
description: The datetime at which this registration was last modified.
section:
type: string
description: The dash-separated full code of the section associated with this Registration.
user:
type: string
readOnly: true
description: The Penn Labs Accounts username of the User who owns this Registration.
cancelled:
type: boolean
readOnly: true
description: '
Defaults to False, changed to True if the registration has been cancelled. A cancelled
registration will not trigger any alerts to be sent even if the relevant section opens.
A cancelled section can be resubscribed to (unlike deleted alerts), and will show up
on the manage alerts page on the frontend (also unlike deleted alerts). Note that once
a registration is cancelled, it cannot be uncancelled (resubscribing creates a new
registration which is accessible via the resubscribed_to field, related name of
resubscribed_from).
'
cancelled_at:
type: string
format: date-time
readOnly: true
nullable: true
description: When was the registration cancelled? Null if it hasn't been cancelled.
deleted:
type: boolean
readOnly: true
description: '
Defaults to False, changed to True if the registration has been deleted. A deleted
registration will not trigger any alerts to be sent even if the relevant section opens.
A deleted section cannot be resubscribed to or undeleted, and will not show up on the
manage alerts page on the frontend. It is kept in the database for analytics purposes,
even though it serves no immediate functional purpose for its original user.
'
deleted_at:
type: string
format: date-time
readOnly: true
nullable: true
description: When was the registration deleted? Null if it hasn't been deleted.
auto_resubscribe:
type: boolean
readOnly: true
description: '
Defaults to False, in which case a registration will not be automatically resubscribed
after it triggers an alert to be sent (but the user can still resubscribe to a sent alert,
as long as it is not deleted). If set to True, the registration will be automatically
resubscribed to once it triggers an alert to be sent (this is useful in the case of
volatile sections which are opening and closing frequently, often before the user has
time to register).
'
notification_sent:
type: boolean
readOnly: true
description: True if an alert has been sent to the user, false otherwise.
notification_sent_at:
type: string
format: date-time
readOnly: true
nullable: true
description: '
When was an alert sent to the user as a result of this registration?
Null if an alert was not sent.
'
last_notification_sent_at:
type: string
readOnly: true
description: '
The last time the user was sent an opening notification for this registration''s
section. This property is None (or null in JSON) if no notification has been sent to the
user for this registration''s section.
This is used on the frontend to tell the user a last time an alert was sent for
the SECTION of a certain registration in the manage alerts page. Since the idea of
Registration objects and resubscribe chains is completely abstracted out of the User''s
understanding, they expect alerts to work by section (so the "LAST NOTIFIED"
column should tell them the last time they were alerted about that section).
'
close_notification:
type: boolean
readOnly: true
description: "Defaults to false. If set to true, the user will receive\n a close notification (an alert when the section closes after an\n alert was sent for it opening).\n"
close_notification_sent:
type: boolean
readOnly: true
description: True if a close notification has been sent to the user, false otherwise.
close_notification_sent_at:
type: string
format: date-time
readOnly: true
nullable: true
description: '
When was a close notification sent to the user as a result of this registration?
Null if a close notification was not sent.
'
is_active:
type: string
readOnly: true
description: '
True if the registration would send an alert when the watched section changes to open,
False otherwise. This is equivalent to
[not(notification_sent or deleted or cancelled) and semester is current].
'
is_waiting_for_close:
type: string
readOnly: true
description: '
True if the registration is waiting to send a close notification to the user
once the section closes. False otherwise.
'
section_status:
type: string
readOnly: true
description: 'The current status of the watched section. Options and meanings: | "O" | "Open" |
| "C" | "Closed" |
| "X" | "Cancelled" |
| "" | "Unlisted" |
'
description: Historic registration detail successfully retrieved.
'403':
description: Access denied (missing or improper authentication).
'404':
description: Historic registration not found with given id.
tags:
- '[PCA] Registration History'
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'