Roles API Endpoint - Course Roles?

[themidiman]

Re: Roles API Endpoint Docs. I'm looking to see a representation of a custom course role at a sub-account. I don't see any endpoints to return data other than what's representative of an Account role. We need to see a data matrix of a course role that is defined within an account. See screenshot of what you can see in the UI:

Account Vs Course Roles in Admin UI

How does one pull just course roles from within an account?

Thanks in advance!

[JamesSekcienski · Accepted solution]

@themidiman 

You will want to use the List Roles endpoint.

GET /api/v1/accounts/:account_id/roles

I know it says the "account_id" request parameter is required, but I haven't included it before and it worked.

I usually include the "show_inherited" request parameter set equal to true to get any roles that may be defined in parent accounts, but you may not need this if you are only looking at what is defined at the specific account level.

When looking at the results, those that have a "base_role_type" of "AccountMembership" will be account roles.  However, the other base role types indicate course roles (i.e. "StudentEnrollment", "TeacherEnrollment", "TaEnrollment", "ObserverEnrollment", "DesignerEnrollment").  There is also an "is_account_role" property that you can check.

I haven't found a way to exclude the account roles from the request results, but they can be filtered out if you only want to look at course roles.

[themidiman]

For reference, I was using the Live API where the required fields cannot be left out. I will use an actual HTTPS API call in Postman and look at the results that way. Thank you!

[JamesSekcienski]

@themidiman 

You're welcome!

As long as it is a GET request and you are logged into Canvas, you can also put the request URL with any parameters directly in the browser to see the results. If you go this route, you may want to use a browser extension that formats JSON to make it easier to read or use the browser's developer tools to look at the Network traffic and see the response in an easier to read format. 

The following URL (when you replace it with your institution's base URL) would show the request results when getting the roles when you go to this URL (put in the address bar).  

https://<YOUR_BASE_URL>/api/v1/accounts/<ACCOUNT_ID_TO_CHECK>/roles?show_inherited=true

Also, depending on the number of roles you have in your system, there is a chance there may be more than one page of results.  You can use the per_page request parameter to increase the number of results you receive by default before you need to go to the next page of results.  Setting it equal to 100 seems to be the maximum allowed value and will also likely cover all roles in your system unless you have over 100 roles.

Example:

https://canvas.instructure.com/api/v1/accounts/1/roles?show_inherited=true&per_page=100

[themidiman]

I'm getting an error message when I leave off the account id:

{
"errors": [
{
"message": "The specified resource does not exist."
}
]
}

Also, if I'm to leave out the account to check, how do I know that the account is showing course roles just belonging to the account?

[themidiman]

I think I get now, what you are saying. For what it's worth you have to include the account so here's my take: First get the roles based from the account and include as many records as possible to not exclude any. Then filter out the 'Enrollment' type roles to get to the ones that are for the course level? It would make more sense to have an additional request parameter to limit to one or the other instead of mixing them together. Thanks again @JamesSekcienski 

[JamesSekcienski]

That's interesting that you received an error when you sent the request.  The account ID should be defined within the request URL, so it shouldn't be needed again as a request parameter too, at least in my experience with using that endpoint.  The account ID in the URL is what specifies the account you want to check for course and account roles.

You are correct that you would need to get all of the roles you can using that endpoint.  Then, after you get them all, you would need to filter them to just get the available course level roles in that account.

I completely agree that another request parameter to limit the results to just course roles or just account roles would be useful and eliminate the need to filter out the type you don't need.  It doesn't look like this exists as an Idea yet based on a quick search.  If you would like you could submit this as an Idea so that hopefully Instructure will consider developing this new feature in the future. Canvas Ideas