8 releases
0.1.7 | Sep 22, 2024 |
---|---|
0.1.6 | Nov 21, 2023 |
#439 in Web programming
115KB
1.5K
SLoC
Canvas LMS Connector
Overview
This documentation introduces the Canvas LMS Connector, a Rust library designed to facilitate interaction with the Canvas Learning Management System (LMS) API. Crafted to integrate Rust applications with the features of Canvas, this library offers an effective solution for data manipulation in educational environments.
The focus of Canvas LMS Connector (canvas_lms_connector
) is to provide an accessible interface for developers seeking to interact with the Canvas API, encompassing everything from automating administrative processes to supporting educational initiatives. The library caters to various needs, ranging from course management to the development of customized applications.
Key Features
- Authentication: Simplifies connecting to the Canvas API, prioritizing simplicity and security in credential management.
- Course Management: Enables access and administration of course-related information, including details on enrollments and content.
- Participant Interactions: Provides resources for managing and communicating with students and instructors.
- Assignments and Submissions: Assists in managing tasks and submissions, aiding in effective academic tracking.
The purpose of this documentation is to provide detailed information on installation, usage, and examples of canvas_lms_connector
application. It is intended to be an informative resource for efficiently utilizing the Canvas API across various development contexts.
Documentation Conventions
This section outlines the conventions used throughout this documentation for the Canvas LMS Connector. Understanding these conventions will help in effectively utilizing this guide and interpreting the information as intended.
Notation and Syntax
- Code and Commands: Text that represents code, commands, or file names is presented in a
monospaced font
. - Placeholders: Text in
<angle brackets>
indicates a placeholder that should be replaced with the relevant value by the user. - Environment Variables: Names of environment variables are written in ALL_CAPS.
Terminology
- API: Refers to the Application Programming Interface provided by the Canvas LMS.
- Canvas: The Canvas Learning Management System, the primary system with which this library interacts.
Highlighting
- Important Notes: Sections marked with Important: contain crucial information for the operation or understanding of certain features.
- Tips and Recommendations: Suggestions and best practices are indicated with Tip: to provide additional guidance.
Examples
- Practical examples are provided throughout the documentation to illustrate usage scenarios and code snippets.
- Example commands or code snippets can be directly copied and used, but may need to be adjusted for specific contexts or environments.
By adhering to these conventions, this documentation aims to provide a clear and consistent guide for users of the canvas_lms_connector
. Should there be any ambiguity or questions regarding the conventions, users are encouraged to seek clarification through the support channels provided.
Getting Started
Prerequisites
Before beginning to work with the "Canvas LMS Connector", ensure that the following prerequisites are met:
System Requirements
- Rust Environment: A working Rust environment is necessary, as the "Canvas LMS Connector" is written in Rust. Rustup is recommended for installing the Rust toolchain.
- Operating System: Compatible with any standard operating system supporting Rust, including Windows, macOS, and Linux.
Knowledge Prerequisites
- Basic Rust Knowledge: Fundamental understanding of Rust programming is required for effectively using the "Canvas LMS Connector".
- Familiarity with Canvas LMS: Basic knowledge of Canvas LMS, including its features and API capabilities, is beneficial. For more information on the Canvas LMS API, refer to the Canvas LMS REST API Documentation.
Canvas API Access
- Canvas Account: Access to a Canvas LMS instance is required, which can be through a school, university, or a personal developer account.
- API Token: An API token from Canvas LMS is needed for authentication. This can be obtained from the Canvas LMS account settings.
Meeting these prerequisites will facilitate a smooth initial setup and an effective use of the "Canvas LMS Connector".
Installation
To install the "Canvas LMS Connector" in your Rust project, follow these steps:
-
Add the Dependency:
- Open your project's
Cargo.toml
file and addcanvas_lms_connector
to the[dependencies]
section:[dependencies] canvas_lms_connector = "latest_version"
- Open your project's
-
Update Your Project:
- Run this command in your project directory to download and install the library:
cargo update
- Run this command in your project directory to download and install the library:
-
Build the Project:
- Compile your project to verify the installation:
cargo build
- Compile your project to verify the installation:
Initial Configuration
To configure the "Canvas LMS Connector" for first-time use, follow these steps:
-
Obtain the Canvas API URL:
- Access your Canvas LMS instance. The URL is typically in the format
https://[your-institution].instructure.com
. - Append
/api/v1
to the end of this URL. For example,https://[your-institution].instructure.com/api/v1
. - This is your Canvas API base URL.
- Access your Canvas LMS instance. The URL is typically in the format
-
Generate an API Token:
- Log in to your Canvas account.
- Navigate to
Account
>Settings
. - Scroll down to
Approved Integrations
and click on+ New Access Token
. - Provide a purpose for the token and set an expiration date if desired.
- Click
Generate Token
to create a new API token. - Securely store the generated token, as it will not be displayed again.
After obtaining the API URL and token, you can test these credentials using the test_canvas_credentials
function provided by the CanvasCredentials
struct. This function helps verify the validity of the API URL and token.
Example usage:
use canvas_lms_connector::credentials::{CanvasCredentials, test_canvas_credentials};
let api_url = "https://your-institution.instructure.com/api/v1";
let access_token = "your_api_token";
let test_result = test_canvas_credentials(api_url, access_token);
match test_result {
Ok(status_code) => println!("Credentials are valid! Status code: {}", status_code),
Err(error_code) => eprintln!("Failed to validate credentials. Error code: {}", error_code),
}
With the API URL and token, you can now set up the "Canvas LMS Connector" in your project. Typically, these values are set as environment variables or configured in a settings file for security and ease of management.
Creating Authentication Credentials Structure
The authentication process in the "Canvas LMS Connector" begins with obtaining a CanvasCredentials
struct, which contains the necessary credentials acquired in the previous steps. This struct plays a crucial role in establishing a secure connection with the Canvas LMS API. The following subsections detail the methods available for obtaining and securely storing these credentials.
-
Interactive Authentication via CLI (Preferred Method):
- The
credentials
method first attempts to retrieve credentials stored in the system's key store. - Example code to retrieve credentials:
use canvas_lms_connector::credentials::{CanvasCredentials, credentials}; let credentials = credentials();
- If not present, it will prompt the user to enter them via the console. These are then stored securely for future use.
- Note on System Key Store Access:
When using the
credentials
method to access credentials from the system's key store, the system may prompt for the user's password. This is a standard security measure to ensure authorized access to sensitive information. It's important to be prepared for this prompt, especially when running the application for the first time or on a new device. - Optionally, for file-based credentials, enable the
use_file_credentials
feature inCargo.toml
:
[features] use_file_credentials = []
- With this feature enabled,
credentials()
checks for a fileconfig.json
in the 'Downloads' directory that contains the following:{ "url_canvas": "https://your-institution.instructure.com/api/v1", "token_canvas": "your_api_token" }
- If present, the credentials are retrieved from the file and used for authentication.
- Warning about File-Based Credentials Method:
While the file-based authentication method (
use_file_credentials
) is convenient, particularly for development purposes, it poses significant security risks and is not recommended for production environments. Storing credentials in a file, such asconfig.json
, can make them vulnerable to unauthorized access. This method should be used with extreme caution and only for development and testing purposes, ensuring that production credentials are managed in a more secure manner.
- Warning about File-Based Credentials Method:
While the file-based authentication method (
- Note on System Key Store Access:
When using the
- The
-
Using the
CanvasCredentials
Structure (For Development Purposes Only):- Direct initialization is recommended only for development.
- Example code:
use canvas_lms_connector::credentials::CanvasCredentials; let credentials = CanvasCredentials { url_canvas: "https://your-institution.instructure.com/api/v1".to_string(), token_canvas: "your_api_token".to_string(), };
These methods ensure authentication with the Canvas LMS for API interactions.
Retrieving Courses
Retrieving courses from the Canvas LMS using the "Canvas LMS Connector" involves two methods returning distinct result types: CanvasResultCourses
for multiple courses and CanvasResultSingleCourse
for a single course.
CanvasResultCourses
Structure:
- Variants:
Ok(Vec<Course>)
: Success with a list of courses.ErrConnection(String)
: Error related to connection issues.ErrCredentials(String)
: Error related to authentication or credentials.
CanvasResultSingleCourse
Structure:
- Variants:
Ok(Course)
: Success with a single course.ErrConnection(String)
: Error related to connection issues.ErrCredentials(String)
: Error related to authentication or credentials.
Fetching All Courses:
use canvas_lms_connector::{Canvas, CanvasCredentials, CanvasResultCourses};
let credentials = CanvasCredentials { ... }; // Initialize with your credentials
match Canvas::fetch_courses_with_credentials(&credentials) {
CanvasResultCourses::Ok(courses) => println!("Courses: {:?}", courses),
CanvasResultCourses::ErrConnection(err) => eprintln!("Connection error: {}", err),
CanvasResultCourses::ErrCredentials(err) => eprintln!("Credentials error: {}", err),
}
Fetching a Single Course by ID:
use canvas_lms_connector::{Canvas, CanvasCredentials, CanvasResultSingleCourse};
let credentials = CanvasCredentials { ... }; // Initialize with your credentials
let course_id: u64 = 123; // Your course ID
match Canvas::fetch_single_course_with_credentials(&credentials, course_id) {
CanvasResultSingleCourse::Ok(course) => println!("Course: {:?}", course),
CanvasResultSingleCourse::ErrConnection(err) => eprintln!("Connection error: {}", err),
CanvasResultSingleCourse::ErrCredentials(err) => eprintln!("Credentials error: {}", err),
}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The "Canvas LMS Connector" is now installed and ready for use in your Rust project.
Documentation
For detailed documentation on how to use Canvas Learning, refer to the official documentation.
License
This project is licensed under the MIT License
Dependencies
~9–26MB
~330K SLoC