openapi: 3.0.2 info: title: Penn Courses API Documentation [Accounts] User [Accounts] User [PCP] Course Recommendations 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] Course Recommendations' description: '' paths: /api/plan/recommendations/: post: operationId: Create Course Recommendations description: '(POST `/api/plan/recommendations/`) This route will optionally take in current and past courses. In order to make recommendations solely on the user''s courses in past and current PCP schedules, simply omit both the curr_courses and past_courses fields in your request. Otherwise, in order to specify past and current courses, include a "curr-courses" and/or "past_courses" attribute in the request that should each contain an array of string course full codes of the form DEPT-XXX (e.g. CIS-120). If successful, this route will return a list of recommended courses, with the same schema as the List Courses route, starting with the most relevant course. The number of recommended courses returned can be specified using the n_recommendations attribute in the request body, but if this attribute is omitted, the default will be 5. If n_recommendations is not an integer, or is <=0, a 400 will be returned. If curr_courses contains repeated courses or invalid courses or non-current courses, a 400 will be returned. If past_courses contains repeated courses or invalid courses, a 400 will be returned. If curr_courses and past_courses contain overlapping courses, a 400 will be returned. User authentication required.' parameters: [] requestBody: content: application/json: schema: type: object properties: curr_courses: type: array description: An array of courses the user is currently planning to take, each specified by its string full code, of the form DEPT-XXXX, e.g. CIS-1200. items: type: string past_courses: type: array description: An array of courses the user has previously taken, each specified by its string full code, of the form DEPT-XXXX, e.g. CIS-1200. items: type: string n_recommendations: type: integer description: The number of course recommendations you want returned. Defaults to 5. responses: '403': description: Access denied (missing or improper authentication). '200': description: Response returned successfully. content: application/json: schema: type: array items: type: object properties: id: type: string readOnly: true description: ' The full code of the course, in the form ''{dept code}-{course code}'' dash-joined department and code of the course, e.g. `CIS-120` for CIS-120.' title: type: string readOnly: true description: ' The title of the course, e.g. ''Programming Languages and Techniques I'' for CIS-120. ' description: type: string readOnly: true description: ' The description of the course, e.g. ''A fast-paced introduction to the fundamental concepts of programming... [etc.]'' for CIS-120. ' semester: type: string readOnly: 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. ' num_sections: type: integer readOnly: true description: The number of sections for this course. course_quality: type: number multipleOf: 0.001 maximum: 10 minimum: -10 readOnly: true description: The average course quality rating for this section, on a scale of 0-4. instructor_quality: type: number multipleOf: 0.001 maximum: 10 minimum: -10 readOnly: true description: The average instructor quality for this section, on a scale of 0-4. difficulty: type: number multipleOf: 0.001 maximum: 10 minimum: -10 readOnly: true description: The average difficult rating for this section, on a scale of 0-4. work_required: type: number multipleOf: 0.001 maximum: 10 minimum: -10 readOnly: true description: The average work required for this section, on a scale of 0-4. recommendation_score: type: number multipleOf: 0.001 maximum: 10 minimum: -10 readOnly: true description: ' The recommendation score for this course if the user is logged in, or null if the the user is not logged in.' credits: type: number multipleOf: 0.01 maximum: 100 minimum: -100 readOnly: true nullable: true description: The number of credits this course takes. This is precomputed for efficiency. '400': description: Invalid curr_courses, past_courses, or n_recommendations (see response). tags: - '[PCP] Course Recommendations' 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'