Skip to content

Canvas API Endpoints Used by the Hypothesis LMS App

Jump to bottom
mkdir-washington-edu edited this page Oct 18, 2023 · 13 revisions

The Hypothesis LMS app includes an optional feature set for Canvas which allows users to:

  • Select PDFs from their Canvas course file repository
  • Create groups within a course corresponding to Sections
  • Launch a reading using an specific Canvas group set

Enabling this feature set requires creating a Canvas developer key before proceeding with app installation.

If a Canvas developer key is not provided during the app install process, users will still be able to create Hypothesis-enabled readings with public URLs and PDFs from their Google Drive accounts.

Canvas admins should know that the Hypothesis accesses the following Canvas API endpoints:

  1. The List Files API (to show the teacher the list of Canvas files to choose from)
  2. The List Folders API (to show the teacher the folder structure of the files)
  3. The Inline Preview URL API (to get a "public" URL for the file so we can show the file to the user and let them annotate it)
  4. The Get a single course API to get a list of a student's sections for a course
  5. The List course sections API to get a list of all a course's sections
  6. The Courses > Get single user API to get a list of a student's sections for showing in SpeedGrader
  7. The Courses > Group Categories to list the available group categories when creating Group assignments
  8. The Group Categories > Groups to allow teachers to switch between different groups of a group assignment
  9. The Course > Groups to get to which group a student belongs in a group category
  10. The Course > List pages to show the teacher the list of Canvas Pages to choose from
  11. The Course > Show page to get a URL for the file so we can show the file to the user and let them annotate it

Scoped dev keys

Canvas allows admins to create scoped developer keys, so that external apps and tools are not granted access to any data that is not required for the app/tool to function. Previously, our LMS app did not specify scopes when requesting an OAuth token, which meant scoped dev keys did not work. This was fixed in https://github.com/hypothesis/lms/issues/806.

The use of scoped dev keys is not encouraged, as we might need to adjust the permissions/scopes needed by our app in the future as we continue to expand the functionality of our app. For those that institutions require the use of scoped dev keys, as of April 2023, here are the permissions currently required:

  • url:GET|/api/v1/courses/:course_id/files
  • url:GET|/api/v1/courses/:course_id/folders
  • url:GET|/api/v1/files/:id/public_url
  • url:GET|/api/v1/courses/:id
  • url:GET|/api/v1/courses/:course_id/sections
  • url:GET|/api/v1/courses/:course_id/users/:id
  • url:GET|/api/v1/courses/:course_id/group_categories
  • url:GET|/api/v1/group_categories/:group_category_id/groups
  • url:GET|/api/v1/courses/:course_id/groups
  • url:GET|/api/v1/courses/:course_id/pages
  • url:GET|/api/v1/courses/:course_id/pages/:url_or_id
  • The Allow Include Parameters checkbox must also be checked (we have to use "includes" parameters to retrieve lists of sections for courses)

If a user has installed the app with a scoped Canvas Developer Key and the Canvas File Picker does not show up, ensure that:

  • The user has checked the correct permissions
  • The developer key is turned on
Clone this wiki locally