Users Endpoint Role Argument Problem

Steven Cinquegrana

I'm trying to figure out how to pass a roles argument value to the School API Users endpoint.


The endpoint reference says to "Please use a comma delimited string".


But JSON doesn't explicitly support this. Generally I think you would need to provide something like

<a href="https://api.sky.blackbaud.com/school/v1/users?roles=Student&roles=Teacher">https://api.sky.blackbaud.com/school/v1/users?roles=Student&roles=Teacher&</a> ...

I can't even get this work in Try It, even using a single role, eg "Student".


Can someone please enlighten me? I searched the forums to no avail.

 

Brian Gray

The "User list" endpoint takes role IDs as arguments - not the names of the roles: "Comma delimited list of role IDs to get users for."

https://api.sky.blackbaud.com/school/v1/users?roles=17426,17425

The "User extended list" endpoint takes BASE role IDs as arguments:

https://api.sky.blackbaud.com/school/v1/users/extended?base_role_ids=14,16

It appears to me that the base role IDs are constant across instances of the Core database, but the role IDs are unique to each instance.


The Roles endpoint - https://api.sky.blackbaud.com/school/v1/roles - returns a list of roles with the role name and both role ID and base role ID.

 

Steven Cinquegrana

Gah! Really?


I see it now, in the argument description.


But everything else I've looked at where an ID is required the field is an Integer and the name ends with _id. Eg Course List wants department_id or level_id. This endpoint wants IDs, names the arg roles, not role_ids, and they are provided as Strings?


Gah! Yet more evidence of developers not adhering to any kind of schema between APIs (or even with their own). Guys, please talk, uffer through the occasional meeting, etc.


Thanks for your input Brian‍.

 

Steven Cinquegrana

More "Gah!"


This endpoint returns the dreaded 500 Internal Server Error if you happen to pass Role IDs separated by anything other than a comma.


I know that scenario sounds unlikely, but it still shouldn't result in a 500; it's a handleable error and should return a 400 Bad Request response, as passing, say, a role_id of "Student" does.


It seems that "If in doubt, throw a 500" is the prevailing default for the SKY API. It shouldn't be. It's lazy, and it can play havoc with consuming code. Please save your 500s for real server errors.


Please fix this, and anything like it, as a 500 response will prompt code to wait and retry where, in cases like this, there is simply no point.


PS You might want to include the role_id with the response records. As it is at the moment, if you pass multiple role_ids as arguments, there is no (easy) way to know which record is associated with which role.