openapi: 3.0.2 info: title: Penn Courses API Documentation [Accounts] User [Accounts] User [PCR] Instructor 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] Instructor Reviews' description: '' paths: /api/review/instructor/{instructor_id}: get: operationId: Retrieve Instructor Reviews description: '(GET `/api/review/instructor/{instructor_id}`) Get all reviews for a given instructor, aggregated by course. User authentication required.' parameters: - name: instructor_id in: path required: true description: The integer id of the instructor you want reviews for. Note that you can get the relative path for any instructor including this id by using the `url` field of objects in the `instructors` list returned by Retrieve Autocomplete Data. schema: type: string responses: '200': content: application/json: schema: properties: name: type: string description: The full name of the instructor. num_sections_recent: type: integer description: The number of sections this instructor taught in his/her most recent semester teaching. num_sections: type: integer description: The number of sections this instructor has taught (that we have data for). average_reviews: type: object description: This instructor's average reviews across all of his/her taught 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: 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 his/her taught sections from only his/her most recent semester teaching 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 num_semesters: type: integer description: The number of semesters this instructor has taught (that we have data for). courses: type: object description: Reviews for this instructor broken down by the courses he/she has taught. Note that each key in this subdictionary is the course full code (indicated by `COURSE_FULL_CODE`; this is not an actual key but a placeholder for potentially many keys). properties: COURSE_FULL_CODE: type: object description: This key `COURSE_FULL_CODE` is a placeholder for potentially many course full code keys. Each full code is the dash-joined department and most-recent (across all codes representing the topic) code of the course, e.g. `CIS-120` for CIS-120. properties: full_code: type: string description: The dash-joined department and most-recent (across all codes representing the topic) code of the course, e.g. `CIS-120` for CIS-120. average_reviews: type: object description: This course's average reviews across all of its sections taught by this instructor 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 taught by this instructor 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 latest_semester: type: string description: The most recent semester this course was taught by this instructor (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 in which this course was taught by this instructor (that we have data for). code: type: string description: Same as `full_code`. name: type: string description: The title of the course, e.g. 'Programming Languages and Techniques I' for CIS-120. description: Reviews retrieved successfully. '403': description: Access denied (missing or improper authentication). '404': description: Instructor with given instructor_id not found. tags: - '[PCR] Instructor 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'