The way you use the Valence Learning Framework API to create sections for course offerings is idiosyncratic. Assume you start with a blank course, that has no descendant org units (no sections, no groups, nothing). In this example, let's fetch the orgstructure data for our Extensibility 106course.
GET /d2l/api/lp/1.3/orgstructure/113459
> {"Name": "Extensibility 106",
"Identifier": "113459",
"Type": {"Name": "Course Offering",
"Code": "Course Offering",
"Id": 3},
"Code": "EXT-106"}
GET /d2l/api/lp/1.3/orgstructure/113459/children
> []
Initialize course with section properties
The first thing you have to do is define the section properties for the course offering: what kind of sections do you want to create under the course offering? To create the section properties for the course offering, you use a SectionPropertyData block; here's one that says "I want this course to have 10 sections and to auto-enroll the students, randomly, into these sections" (EnrollmentStyle 2 corresponds to NumberOfSectionsAutoEnrollment):
{"AutoEnroll": true,
"EnrollmentQuantity": 10,
"EnrollmentStyle": 2,
"RandomizeEnrollments": true}
Now, to initialize the course with these settings, and have the first default section(s) created, we PUT that block to this route:
PUT /d2l/api/lp/1.3/113459/sections/
> [{"SectionId":113460,
"Name":"Section 1",
"Description":{"Text":"","Html":""},
"Enrollments":[]},
...
{"SectionId":113469,
"Name":"Section 10",
"Description":{"Text":"","Html":""},
"Enrollments":[]}
]
Notice that with this call, we've now created 10 sections as children of this course offering, and the back-end service has automatically generated names (and codes) for them.
Add a new section after the fact
Now suppose we want to add an eleventh section to this course. First, we need to use a SectionData block for the new section's properties:
{"Name": "Section 11",
"Code": "Sec11",
"Description": {"Content": "New Section Descr.", "Type": "Text} }
(Note: When you form this block to create the new section you have to use a RichTextInput type structure for the Description property. When you get the properties for a section back from the service, it writes the description using the RichText property instead. This is a common sticky point for devs new to the framework.)
Then, you POST that block to this route:
POST /d2l/api/lp/1.3/113459/sections/
> {"SectionId":113470,
"Name":"Section 11",
"Description":{"Text":"Description","Html":""},
"Enrollments":[]}
You'll get back the properties for the newly created section.
Summary
So, "why PUT and then POST"? Yes, it is a bit confusing, but think of it this way:
- The first use, of PUT, is to update the "section properties" attribute for a course offering (as a consequence, when a course offering's section properties are initially defined, as a side effect, the back-end creates the section org units needed to go along with those new settings).
- The second use, of POST, is to create a new org unit (a new section), and assign it to the course offering.
Note: This API Recipe was created in response to a question on StackOverflow.