openapi: 3.0.2
info:
  title: Penn Courses API Documentation [Accounts] User [Accounts] User [PCR] Course Reviews 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: '[PCR] Course Reviews'
  description: ''
paths:
  /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
                              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
                          latest_semester:
                            type: string
                            description: The most recent semester this instructor taught this course (of the form YYYYx where x is A [for spring], B [summer], or C [fall]), e.g. `2019C` for fall 2019.
                          num_semesters:
                            type: integer
                            description: The number of semesters that this instructor has taught this course (that we have data for).
                          name:
                            type: string
                            description: The instructor's name
          description: Reviews retrieved successfully.
        '403':
          description: Access denied (missing or improper authentication).
        '404':
          description: Course with given course_code not found.
      tags:
      - '[PCR] Course Reviews'
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'