canvas-procs.tcl

Publicity: Public Only All

canvas-procs.tcl

Support for the Canvas REST API The Canvas REST API provides proper encodings for query and POST parameters (requests can be submitted as url-encoded or as JSON) and translates the reply into Tcl dicts. The API support also Canvas Pagination (https://canvas.instructure.com/doc/api/file.pagination.html) To call the Canvas REST API, one has to create an "app", which must acquire an access token from the Microsoft identity platform. The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph. To get an access token, your app must be registered with the Microsoft identity platform and be authorized by either a user or an administrator for access to the Microsoft Graph resources it needs. https://docs.microsoft.com/en-us/graph/auth/auth-concepts https://docs.microsoft.com/en-us/graph/auth-register-app-v2 In theory, this API will allow later to switch to newer versions of the Graph API when newer versions (currently post 1.0) of the Microsoft Graph API will come out.
This file defines the following Objects and Classes: ::canvas::API

Location:

packages/xooauth/tcl/canvas-procs.tcl
Author:

Gustaf Neumann

Procedures in this file

Class ::canvas::API (public)
canvas::API instproc paginated_result_list (protected)
canvas::API instproc params (protected)
canvas::API instproc parse_link_params (protected)
canvas::API instproc parse_link_value (protected)
canvas::API instproc request (protected)
canvas::API instproc token (public)
canvas::API instproc {account admins} (public)
canvas::API instproc {account courses} (public)
canvas::API instproc {account get} (public)
canvas::API instproc {account list} (public)
canvas::API instproc {account permissions} (public)
canvas::API instproc {account settings} (public)
canvas::API instproc {course activities} (public)
canvas::API instproc {course todo} (public)
canvas::API instproc {course users} (public)

Detailed information

Class ::canvas::API (public)

 ::nx::Class ::canvas::API [ -baseurl baseurl ] [ -token token ] \
    [ -version version ]

Basic Canvas API for OAuth calls. For details, see https://canvas.instructure.com/doc/api/

Switches:

-baseurl
(optional)
starting URL
-token
(optional)
auth token
-version
(optional)
Version of the API

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method paginated_result_list (protected)

 <instance of canvas::API> paginated_result_list \
    [ -max_entries max_entries ] r expected_status_code

By default, Canvas returns for a query just the first 10 results ("pagination"). To obtain more results, it is necessary to issue multiple requests. If "max_entries" is specified, the interface tries to get the requested number of entries. If there are less entries available, just these are returned.

Switches:

-max_entries
(optional)

Parameters:
r
expected_status_code

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method params (protected)

 <instance of canvas::API> params varlist

parameter encoding following the parameter conventions in Canvas

Parameters:
varlist

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method parse_link_params (protected)

 <instance of canvas::API> parse_link_params pairs

Parameters:
pairs

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method parse_link_value (protected)

 <instance of canvas::API> parse_link_value link

Parse the provided link.

Parameters:
link

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method request (protected)

 <instance of canvas::API> request -method method  \
    [ -content_type content_type ] [ -token token ] [ -vars vars ] \
    -url url

Switches:

-method
(required)
-content_type
(defaults to "application/json; charset=utf-8") (optional)
-token
(optional)
-vars
(optional)
-url
(required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method token (public)

 <instance of canvas::API> token [ -grant_type grant_type ] \
    [ -scope scope ] [ -assertion assertion ] \
    [ -client_assertion_type client_assertion_type ] \
    [ -requested_token_use requested_token_use ]

Get bearer token (access token) from the /oauth2/v2.0/token endpoint. https://canvas.instructure.com/doc/api/file.oauth_endpoints.html#post-login-oauth2-token

Switches:

-grant_type
(defaults to "client_credentials") (optional)
-scope
(optional)
-assertion
(optional)
-client_assertion_type
(defaults to "urn:ietf:params:oauth:client-assertion-type:jwt-bearer") (optional)
-requested_token_use
(optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method account admins (public)

 <instance of canvas::API> account admins [ -page page ] \
    [ -per_page per_page ] [ -max_entries max_entries ] account_id

Get a paginated list of the admins in the account. Details: https://canvas.instructure.com/doc/api/admins.html

Switches:

-page
(defaults to "1") (optional)
Return the nth page of the result set
-per_page
(defaults to "10") (optional)
Return this number of entries per page
-max_entries
(optional)
perform potentially multiple requests until the requested number of entries can be returned.

Parameters:
account_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method account courses (public)

 <instance of canvas::API> account courses \
    [ -with_enrollments with_enrollments ] \
    [ -enrollment_type enrollment_type ] [ -published published ] \
    [ -completed completed ] [ -blueprint blueprint ] \
    [ -blueprint_associated blueprint_associated ] \
    [ -by_teachers by_teachers ] [ -by_subaccounts by_subaccounts ] \
    [ -hide_enrollmentless_courses hide_enrollmentless_courses ] \
    [ -state state ] [ -enrollment_term_id enrollment_term_id ] \
    [ -search_term search_term ] [ -include include ] [ -sort sort ] \
    [ -order order ] [ -search_by search_by ] \
    [ -starts_before starts_before ] [ -ends_after ends_after ] \
    [ -homeroom homeroom ] [ -page page ] [ -per_page per_page ] \
    [ -max_entries max_entries ] account_id

Retrieve a paginated list of courses in this account. Details: https://canvas.instructure.com/doc/api/accounts.html

Switches:

-with_enrollments
(optional)
If true, include only courses with at least one enrollment. If false, include only courses with no enrollments. If not present, do not filter on course enrollment status.
-enrollment_type
(optional)
If set, only return courses that have at least one user enrolled in the course with one of the specified enrollment types. Allowed values: teacher, student, ta, observer, designer
-published
(optional)
If true, include only published courses. If false, exclude published courses. If not present, do not filter on published status.
-completed
(optional)
If true, include only completed courses (these may be in state 'completed', or their enrollment term may have ended). If false, exclude completed courses. If not present, do not filter on completed status.
-blueprint
(optional)
If true, include only blueprint courses. If false, exclude them. If not present, do not filter on this basis.
-blueprint_associated
(optional)
If true, include only courses that inherit content from a blueprint course. If false, exclude them. If not present, do not filter on this basis.
-by_teachers
(optional)
List of User IDs of teachers; if supplied, include only courses taught by one of the referenced users.
-by_subaccounts
(optional)
List of Account IDs; if supplied, include only courses associated with one of the referenced subaccounts.
-hide_enrollmentless_courses
(optional)
If present, only return courses that have at least one enrollment. Equivalent to 'with_enrollments=true'; retained for compatibility.
-state
(optional)
If set, only return courses that are in the given state(s). By default, all states but “deleted” are returned. Allowed values: created, claimed, available, completed, deleted, all.
-enrollment_term_id
(optional)
If set, only includes courses from the specified term.
-search_term
(optional)
If set, only includes courses from the specified term.
-include
(optional)
List of extra values to be included. Allowed values: syllabus_body, term, course_progress, storage_quota_used_mb, total_students, teachers, account_name, concluded
-sort
(optional)
The column to sort results by. Allowed values: course_name, sis_course_id, teacher, account_name
-order
(optional)
the order to sort the given column by. Allowed values: asc, desc
-search_by
(optional)
The filter to search by. “course” searches for course names, course codes, and SIS IDs. “teacher” searches for teacher names Allowed values: course, teacher
-starts_before
(optional)
If set, only return courses that start before the value (inclusive) or their enrollment term starts before the value (inclusive) or both the course's start_at and the enrollment term's start_at are set to null. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
-ends_after
(optional)
If set, only return courses that end after the value (inclusive) or their enrollment term ends after the value (inclusive) or both the course's end_at and the enrollment term's end_at are set to null. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
-homeroom
(optional)
If set, only return homeroom courses.
-page
(defaults to "1") (optional)
Return the nth page of the result set
-per_page
(defaults to "10") (optional)
Return this number of entries per page
-max_entries
(optional)
perform potentially multiple requests until the requested number of entries can be returned.

Parameters:
account_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method account get (public)

 <instance of canvas::API> account get account_id

Retrieve information on an individual account, given by id or sis sis_account_id. Details: https://canvas.instructure.com/doc/api/accounts.html

Parameters:
account_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method account list (public)

 <instance of canvas::API> account list [ -page page ] \
    [ -per_page per_page ] [ -max_entries max_entries ]

A paginated list of accounts that the current user can view or manage. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in. Details: https://canvas.instructure.com/doc/api/accounts.html

Switches:

-page
(defaults to "1") (optional)
Return the nth page of the result set
-per_page
(defaults to "10") (optional)
Return this number of entries per page
-max_entries
(optional)
perform potentially multiple requests until the requested number of entries can be returned.

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method account permissions (public)

 <instance of canvas::API> account permissions \
    [ -permissions permissions ] account_id

Returns permission information for the calling user and the given account. You may use `self` as the account id to check permissions against the domain root account. The caller must have an account role or admin (teacher/TA/designer) enrollment in a course in the account. Details: https://canvas.instructure.com/doc/api/accounts.html

Switches:

-permissions
(optional)

Parameters:
account_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method account settings (public)

 <instance of canvas::API> account settings account_id

Returns all of the settings for the specified account as a JSON object. The caller must be an Account admin with the manage_account_settings permission. Details: https://canvas.instructure.com/doc/api/accounts.html

Parameters:
account_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method course activities (public)

 <instance of canvas::API> course activities [ -page page ] \
    [ -per_page per_page ] [ -max_entries max_entries ] course_id

Returns the paginated Returns the current user's course-specific activity stream, paginated. Details: https://canvas.instructure.com/doc/api/courses.html

Switches:

-page
(defaults to "1") (optional)
Return the nth page of the result set
-per_page
(defaults to "10") (optional)
Return this number of entries per page
-max_entries
(optional)
perform potentially multiple requests until the requested number of entries can be returned.

Parameters:
course_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method course todo (public)

 <instance of canvas::API> course todo [ -page page ] \
    [ -per_page per_page ] [ -max_entries max_entries ] course_id

Returns a paginated list of the current user's course-specific todo items. Details: https://canvas.instructure.com/doc/api/courses.html

Switches:

-page
(defaults to "1") (optional)
Return the nth page of the result set
-per_page
(defaults to "10") (optional)
Return this number of entries per page
-max_entries
(optional)
perform potentially multiple requests until the requested number of entries can be returned.

Parameters:
course_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

canvas::API method course users (public)

 <instance of canvas::API> course users \
    [ -search_term search_term ] [ -sort sort ] \
    [ -enrollment_type enrollment_type ] \
    [ -enrollment_role_id enrollment_role_id ] [ -include include ] \
    [ -user_ids user_ids ] [ -enrollment_state enrollment_state ] \
    [ -page page ] [ -per_page per_page ] [ -max_entries max_entries ] \
    course_id

Returns the paginated list of users in this course. And optionally the user's enrollments in the course. Details: https://canvas.instructure.com/doc/api/courses.html

Switches:

-search_term
(optional)
The partial name or full ID of the users to match and return in the results list.
-sort
(optional)
When set, sort the results of the search based on the given Allowed values: username, last_login, email, sis_id
-enrollment_type
(optional)
When set, only return users where the user is enrolled as this type. “student_view” implies include[]=test_student. This argument is ignored if enrollment_role is given. Allowed values: teacher, student, student_view, ta, observer, designer
-enrollment_role_id
(optional)
When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the Add Role API or a built_in role id with type 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.
-include
(optional)
Optionally included content. Allowed values: enrollments, locked, avatar_url, test_student, bio, custom_links, current_grading_period_scores, uuid
-user_ids
(optional)
If included, the course users set will only include users with IDs specified by the param.
-enrollment_state
(optional)
When set, only return users where the enrollment workflow state is of one of the given types. “active” and “invited” enrollments are returned by default. Allowed values: active, invited, rejected, completed, inactive
-page
(defaults to "1") (optional)
Return the nth page of the result set
-per_page
(defaults to "10") (optional)
Return this number of entries per page
-max_entries
(optional)
perform potentially multiple requests until the requested number of entries can be returned.

Parameters:
course_id

Partial Call Graph (max 5 caller/called nodes):

Testcases:
No testcase defined.

[ show source ]