Penn Course Review API overview

Purpose: This document (1) helps us write the API and (2) is used by API consumers to understand its functionality.

Notes:

The Penn Course Review API

is a simple RESTful API to the data available on PennCourseReview.com. The easiest way to explain it is to look at some queries.

Return type: The results will be JSON Objects, which you should be able to turn into a dictionary in whatever language you are working with, using something like json_decode.

Note: All non-canonical links (i.e. redirects) are in blue. The most important canonical links are in red (common access points, or special information).

Usage:

All queries will be of the form http://api.penncoursereview.com/v1/[query]?token=public

Note: For security purposes, the string "?token=public" must be appended to the end of each query.

Example Query:

http://api.penncoursereview.com/v1/coursehistories/CIS-120?token=public

The following are descriptions and sample output of available queries.

Top-Level Lists:

Resources:

#Course resource, e.g. "CIS-120 in 2011c".

Note that a Course may have multiple aliases (crosslistings): "Intro to Cognitive Science" is one Course with five aliases ("CIS-140", "COGS-001", "PSYC-107", "PHIL-044", "LING-105")

A Course can be accessed from the following paths:

A Course has the following subpaths:

#Section resource, e.g. "CIS-120-001 in 2011c".

A Section can be accessed from the following paths:

A Section has the following subpaths:

#Review resource.

A Review contains several ratings.

The ratings correspond to the following questions:

RatingQuestion
rCourseQualityOverall Quality of the course.
rInstructorQualityOverall Quality of the instructor.
rDifficultyPlease rate the difficulty of the course. (0=easy to 4=difficult)
rCommAbilityInstructor's ability to communicate the subject matter.
rInstructorAccessInstructor's accessibility and willingness to to discuss course content and any problems.
rReadingsValueValue of assigned readings.
rAmountLearnedAmount learned from this course in terms of knowledge, concepts, skills and thinking ability.
rWorkRequiredPlease rate the amount of work required for this course. (0=very little to 4=very much)
rRecommendMajorWould you recommend this course to a major? (0=no to 4=strongly)
rRecommendNonMajorWould you recommend this course to a non-major? (0=no to 4=strongly)
rStimulateInterestWas the instructor able to stimulate your interest in the material?
rArticulateGoalsWere the goals of the course clearly articulated?
rSkillEmphasisWas the emphasis placed on the language skills (speaking, listening, reading writing) appropriate in terms of the defined goals of the course?
rHomeworkValuableWere homework exercises (and compositions, where appropriate) valuable reinforcement of classroom work?
rExamsConsistentWere the exams consistent with assignments, materials, and method of instruction?
rAbilitiesChallengedWere your linguistic abilities in reading, writing, speaking, and listening sufficiently challenged?
rClassPaceHow would you rate the pace of the course? (0=much to slow; 1=too slow; 2=just right; 3=too fast; 4=much too fast)
rOralSkillsDid the instructor organize appropriate activities in class to encourage the use of oral skills?
rInstructorConcernWas the instructor concerned that students learn the materials?
rInstructorRapportPlease evaluate the rapport between the class and the instructor. (0=bad, 4=excellent)
rInstructorAttitudePlease rate the instructor's attitude towards the course.
rInstructorEffectivePlease rate the instructor's effectiveness in presenting and explaining course materials.
rGradeFairnessPlease rate the fairness of the grading process in the course.
rNativeAbilityDo you feel that the skills learned in this course would help you survive in a native environment?
rTAQualityPlease evaluate the overall quality of the teaching assistant/drill instructor in the course.

If accessed from a Section, a Review also contains a full text review.

A Review cannot be accessed from the top-level; it can be accessed from a Section, Course, or Instructor.

#Instructor resource.

An Instructor can be accessed from the following paths:

An Instructor has the following subpaths:

#Course History, e.g. "CIS-120"

A course history is a course over time; it has no associated semester. It also includes previous names. For example, the course history of CIS-160 includes the last several semesters of CIS-160, CIS-260, and CSE-260.

A Course History can be accessed from the following paths:

A Course History has the following subpaths:

#Building

### BUILDING DATA NOT CURRENTLY AVAILABLE ###

A Building can be accessed from the following path:

A Building has the following subpaths

#Department (if top-level)

A Department can be accessed from the following paths:

A Department has the following subpaths:

Note: These is not the only type of resources available, but understanding what these offer should help

Descriptive Aliases, for discovery, etc

/semesters
/semester/current #points to whatever's most recent # NOT PERMANENT
/semester/2011c
/semester/2011c/dept/CIS
/semester/2011c/dept/CIS/courses/120 # alias for /courses/2041
/semester/2011c/dept/CIS/courses/120/section/001 #alias for /courses/2041/section/001

/dept/CIS/courses/120 # alias for /coursehistory/CIS-120

Short Aliases, for convenience and easy API calls

/CIS-121 #alias for /coursehistory/CIS-121 #NOT PERMANENT!
/2010c-CIS-121 #alias for /semester/2010c/dept/CIS/courses/121
/2010c-CIS-121-001 #alias for /semester/2010c/dept/CIS/courses/121/section/001

API Calls that we expect pages to make

Note: see https://gomockingbird.com/mockingbird/#fi6qy0z/ for mockups

Course Page:

/CIS-121 # a Course History
/CIS-121/reviews
/courses/2011c-CIS-121-001/review # full text review

Instructor Page:

/instructor/ # an Instructor
/instructor//reviews
/courses/2011c-CIS-121-001/review # full text review