canvasapi/
lib.rs

1//! This is the (unofficial) Rust version of the library for accessing the Canvas LMS API.
2//! The documentation of the official API can be found
3//! [here](https://canvas.instructure.com/doc/api/).
4//!
5//! This client that is used for making the calls is [reqwest](https://crates.io/crates/reqwest).
6//! The API calls are by default asynchronous.
7//! The [Tokio](https://crates.io/crates/tokio) runtime is used for the tests.
8//!
9//! # Feature flags
10//!
11//! - `blocking`: enables blocking requests.
12//! - `devel`: enables functions that are still in development.
13//!
14//! # Quickstart
15//!
16//! First, the information about the Canvas LMS server needs to be stored in a `CanvasInformation`
17//! struct.
18//! Using this information, the correct request URL's are created and, with a valid API token,
19//! executed.
20//!
21//! ```
22//! # use canvasapi::prelude::*;
23//! # tokio_test::block_on(async {
24//! # dotenv::dotenv().ok();
25//! let base_url = std::env::var("CANVAS_BASE_URL").unwrap();
26//! let canvas_token = std::env::var("CANVAS_ACCESS_TOKEN").unwrap();
27//!
28//! let canvas = CanvasInformation::new(&base_url, &canvas_token);
29//! let course = Canvas::get_course(13369).unwrap().fetch(&canvas).await.unwrap().inner();
30//! # });
31//! ```
32//!
33//! # Contributing
34//!
35//! This crate only supports GET requests, and not all of them are implemented.
36//! Only the ones I use are implemented.
37//! Feel free to add more.
38//!
39//! To add support for new request, follow these steps:
40//! 1. Canvas will return data in the form of JSON. This data needs to be deserialized into
41//!    a struct. Define this struct in this library, under `models`, when it is not yet defined.
42//!    This information can be retrieved using the official Canvas API.
43//! 2. API request functions can are added in the implementation of the structs. These requests can
44//!    be methods or functions. To define a new request, use the `api_get!` macro. The following
45//!    example shows the usage of the macro.
46//!
47//! ```ignore
48//! impl Course {
49//!     api_get! {
50//!         /// Get all courses from the current user.
51//!         courses():
52//!             "courses" =>
53//!             () -> () -> [Course]
54//!     }
55//!
56//!     api_get! {
57//!         /// Return the assignment with the given id.
58//!         get_assignment(self):
59//!             "courses/{id}/assignments/{assignment_id}" =>
60//!                 (id: self.id) -> (assignment_id: usize) -> Assignment
61//!     }
62//!
63//!     api_get! {
64//!         /// Get only the students from the course.
65//!         get_students(self):
66//!             "courses/{id}/search_users" =>
67//!                 (id: self.id) -> () -> [User]
68//!                 [EnrollmentType::Student]
69//!     }
70//!
71//!     api_get! {
72//!         /// This is still in development.
73//!         function_in_developmen():
74//!             "test" =>
75//!                 () -> () -> Test
76//!             features = [(name = "devel", reason = "Function is not ready yet.")]
77//!     }
78//!
79//!     api_todo! {
80//!         /// This function still needs to be fully implemented.
81//!         function_that_is_todo()
82//!     }
83//! }
84//! ```
85//!
86//! First, you write the (optional) documentation string, for use in this generated
87//! documentation, followed by the function/method name.
88//! If it is a method, the `self` keyword is used between the parentheses.
89//! Next, you write the request url, without the base url and without `/api/v1/`.
90//! The full request is generated using the `CanvasInformation` struct.
91//! The request url can contain named parameters.
92//! The `self` arguments are defined in the first group and the function arguments are
93//! passed in the second group.
94//! Finaly, the return type of the request is defined by passing the returned struct.
95//! Square brackets are used when a `Vec` is returned by the API.
96//! Optionaly, requests parameters can be added.
97
98#![allow(dead_code, unused)]
99
100#[macro_use]
101pub mod parameters;
102#[macro_use]
103mod requests;
104
105pub mod canvas;
106pub mod models;
107
108pub mod prelude {
109    pub use super::canvas::CanvasInformation;
110    pub use super::models::prelude::*;
111    pub use super::parameters::*;
112}
canvasapi/lib.rs

canvasapi/
lib.rs
