In this API Cookbook Recipe, we'll review the specific APIs that sample uses to retrieve courses, departments and semesters.
Before we look at the APIs, let's review the typical hierarchy of the default OrgUnit types:
From the diagram, we see that semesters are the direct children of the root org unit, so we can retrieve a list of all semesters by using the Organizational Structure API to request a list of children of the root org and limiting the results to semester objects by specifying their ouTypeId. In this example, semesters have an ouTypeId of 5 and the root org has an orgUnitId of 6606.
GET /d2l/api/lp/1.0/orgstructure/6606/descendants/?ouTypeId=5Response:200 OK[{"Identifier": "121194","Name": "Fall 2012 Semester","Code": "Fall2012","Type": {"Id": 5,"Code": "Semester","Name": "Semester"}{"Identifier": "122037","Name": "Winter 2013 Semester","Code": "Winter2013","Type": {"Id": 5,"Code": "Semester","Name": "Semester"}}}]
Similar to semesters, departments are also the direct children of the root org. So we can get a list of departments by retrieving the children of the root org and limiting the results by specifying the ouTypeId of departments. In this example, the outTypeId for departments is 203.
GET /d2l/api/lp/1.0/orgstructure/6606/children/?ouTypeId=203Response:200 OK[{"Identifier": "121162","Name": "Actuarial Science","Code": "ACTSC","Type": {"Id": 203,"Code": "Department","Name": "Department"}},{"Identifier": "121139","Name": "Philosophy","Code": "PHIL","Type": {"Id": 203,"Code": "Department","Name": "Department"}},{"Identifier": "121140","Name": "Digital Arts Communication","Code": "DAC","Type": {"Id": 203,"Code": "Department","Name": "Department"}}]
Intuitively, we can retrieve the course templates within a department by listing its children. In this example, we would like to view the course template for Actuarial Science department which has an orgUnitId of 121162.
GET /d2l/api/lp/1.0/orgstructure/121162/children/Response:200 OK[{"Identifier": "121195","Name": " 2nd year Actuarial Science Courses","Code": "ACTSC_COURSE_TEMPLATE","Type": {"Id": 2,"Code": "Course Template","Name": "Course Template"}}]
Similar to retrieving a list of course templates within a department, we can make an API call to get the list of courses within each individual template. In this example, our query fetches the list of 2nd year Actuarial Science courses.
GET /d2l/api/lp/1.0/orgstructure/121195/children/Response:200 OK[{"Identifier": "121196","Name": "Mathematics of Investment","Code": "ACTSC221","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}},{"Identifier": "121197","Name": "Mathematics of Finance","Code": "ACTSC231","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}},{"Identifier": "121198","Name": "Intro to Actuarial Mathematics","Code": "ACTSC232","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}}]
We can also fetch the courses listed in all the templates within a department by listing all of its descendants (children and their children) and then limiting the results by specifying the ouTypeId for a course object. In this example, our query will fetch every course in the Actuarial Science department by specifying the ouTypeId of 3.
GET /d2l/api/lp/1.0/orgstructure/121162/descendants/?ouTypeId=3Response:200 OK[{"Identifier": "121196","Name": "Mathematics of Investment","Code": "ACTSC221","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}},{"Identifier": "121199","Name": "Life Contingencies 1","Code": "ACTSC331","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}},{"Identifier": "121204","Name": "Asset-Liability Management","Code": "ACTSC445","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}}]
From the diagram, we see that a semester's children are the course offerings listed during that semester. To fetch a list of all courses within a semester, we use the API to list the children under the semester's orgUnitId. In this example we'll retrieve the children of the Fall 2013 semester, which has an OrgUnitId of 121194.
GET /d2l/api/lp/1.0/orgstructure/121194/children/Response:200 OK[{"Identifier": "121198","Name": "Intro to Actuarial Mathematics","Code": "ACTSC232","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}},{"Identifier": "121702","Name": "Algebra for Hons Mathematics","Code": "MATH135","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}},{"Identifier": "121243","Name": "Intro to Plant Structure & Function","Code": "BIOL120","Type": {"Id": 3,"Code": "Course Offering","Name": "Course Offering"}}]
On the other hand, if we would like to know when a particular course is being offered, we can make an API call to fetch the list of all course offerings. In this example, we specify the course's orgUnitId 121198 and the ouTypeId for semester.
GET /d2l/api/lp/1.0/orgstructure/121198/parents/?outypeid=5Response:200 OK[{"Identifier": "121194","Name": "Fall 2012 Semester","Code": "Fall2012","Type": {"Id": 5,"Code": "Semester","Name": "Semester"}},{"Identifier": "122037","Name": "Winter 2013 Semester","Code": "Winter2013","Type": {"Id": 5,"Code": "Semester","Name": "Semester"}}]
From this example, we can see that the course is being offered in both the Fall 2012 Semester and Winter 2013 Semester.
As we've seen, there are a number of approaches to searching for courses using the APIs.
