API query parameter syntax

[swaldie]

I'm working with the Enrollments endpoint, and the live API displays the following request URL when filtering on enrollment type:

.../api/v1/courses/2624/enrollments?type[]=TeacherEnrollment&type[]=StudentEnrollment

The intention being to limit the results to enrollment objects with a type of either TeacherEnrollment OR StudentEnrollment.

And though this syntax appears to be working, can I form this any another way?

E.g., ...?type=TeacherEnrollment,StudentEnrollment&...

[jerry_nguyen]

@swaldie 

No, you have to form the request URL as dictated by Canvas. The bracket "[]" represents an array. If you send a request as ?parameter=x,z the endpoint will interpret it as a string "x,z" rather than as an individual item. 

Alternatively, instead of building your request with an URL, you can send the request as JSON. E.g.

{
"role": [
    "TeacherEnrollment",
    "StudentEnrollment"
  ]
}

[swaldie]

Thank you, @jerry_nguyen.

And if I may ask, how does that actually look appended to this:

.../api/v1/courses/2624/enrollments?

And let's say that I wanted to filter not only on role/type attribute, but also on the state attribute, allowing for both "active" and "inactive"?

IOW, what does this look like, using your json technique, if I want to return all enrollment objects for course with id = 2624, and with a status of either active or inactive and with a role of either teacher or student?

Thanks again!

[jerry_nguyen · Accepted solution]

@swaldie 

You need to append it with &paremeter[]=xyz&parameter[]=abc and to filter by enrolment status, append this parameter state[] in your request. E.g.

/api/v1/courses/(course id)/enrollments?type[]=TeacherEnrollment&type[]=StudentEnrollment&state[]=active&state[]=invited

If you want to get a full list of enrollments for a course, simply send a request to /enrollments without any parameters.

For JSON, you can use Postman and follow the instructions here: https://community.canvaslms.com/t5/Canvas-Admin-Discussion/API-POST-Global-Announcement-to-Specific-...

[swaldie]

Exactly what I needed.

Thank you!