Thursday, June 21, 2018

REST API "User"

More Blackboard vendors are moving away from native Building Blocks and WebServices to LTI and REST API.

However, the vendor can just casually ask to set up a REST API user with "administrator" privileges.

We had one REST API integration for a pilot project, where most REST API calls could be accomplished by having the REST API User an "instructor" in the course.

However, there was one REST API call that needed higher privileges.


So how we did it:

I. Find out what API call(s) need higher privileges
Vendor needed to get a particular user's course memberships.

API: /learn/api/public/v1/users/{userId}/courses



II. Determine what custom privileges necessary for the REST API call(s) 
I looked up the API call (on developer.blackboard.com)

Users can always view their own memberships. Callers viewing the memberships of another user require at least one of the following entitlements:
'system.user.course.enrollment.VIEW' allows callers to see course memberships
'system.user.org.enrollment.VIEW' allows callers to see organization memberships


Note: this is also a good time to verify that your version of Blackboard meets the minimum version to support  this particular REST API call!

III. Set up a custom privilege role set so we can assign privileges the REST API call(s) require


We have Community license, and prior experience with custom privs for school-level domain administrators. We'd already had a privilege set for these school-level domain admins to see all users.

DOMAIN_USERS Custom Privileges:

  • Administrator Panel (Users) > Users 
  • Administrator Panel (Users) > Users > Edit > View Course Enrollments 
  • Administrator Panel (Users) > Users > Edit > View Organization Enrollments 

IV. Set up (Community license) Domain for that vendor's user so we can assign custom privilege role set to it, and control scope (if necessary) 

We set up a Domain for the vendor: APP_REST_API_VENDORNAME

With Collection:

  • Users > Collection Options: Include all items 
Note: we could do a little more lock down if necessary (if there's a way to craft a course/user collection to be more targeted) ; but since this was a pilot and the REST API User was associated directly with the pilot course(s) we didn't need to do more.

V. Add REST API User as Domain Administrator w/ the custom privilege role set 

I added the REST_API_USER as domain administrator to APP_REST_API_VENDORNAME with our existing DOMAIN_USERS Custom Privileges.

VI. Test
  • Test the REST API Call(s) as the REST API User.
  • Get vendor confirmation they could make REST API call(s), and it was sufficient for their needs. 


No comments:

Post a Comment