1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

//! This is the (unofficial) Rust version of the library for accessing the Canvas LMS API.
//! The official documentation of the API can be found
//! [here](https://canvas.instructure.com/doc/api/).
//!
//! # Quickstart
//!
//! First, the information about the Canvas LMS server needs to be stored in a `CanvasInformation`
//! struct.
//! Using this information, the correct request URL's are created and, with a valid API token,
//! executed.
//!
//! ```
//! # use canvasapi::prelude::*;
//! # #[tokio::test]
//! # async fn get_course_test() {
//! # dotenv::dotenv().ok();
//! let base_url = std::env::var("CANVAS_BASE_URL").unwrap();
//! let canvas_token = std::env::var("CANVAS_ACCESS_TOKEN").unwrap();
//!
//! let canvas = CanvasInformation::new(&base_url, &canvas_token);
//!
//! let course = Canvas::get_course(13369).fetch(&canvas).await.unwrap().inner();
//! # }
//! ```
//!
//! # Notes
//!
//! This crate only supports GET requests, and not all of them are implemented.
//! Only the ones I use are implemented.
//! Feel free to add more.
//!
//! To add support for new request, follow these steps:
//! 1. Canvas will return data in the form of JSON. This data needs to be deserialized into
//!    a struct. Define this struct in this library, under `models`, when it is not yet defined.
//!    This information can be retrieved using the official Canvas API.
//! 2. API request functions can are added in the implementation of the structs. These requests can
//!    be methods or functions. To define a new request, use the `api_get!` macro. The following
//!    example shows the usage of the macro.
//!
//! ```ignore
//! impl Course {
//!     api_get! {
//!         /// Get all courses from the current user.
//!         courses():
//!             "courses" =>
//!             () -> () -> [Course]
//!     }
//!
//!     api_get! {
//!         /// Return the assignment with the given id.
//!         get_assignment(self):
//!             "courses/{id}/assignments/{assignment_id}" =>
//!                 (id: self.id) -> (assignment_id: usize) -> Assignment
//!     }
//!
//!     api_get! {
//!         /// Get only the students from the course.
//!         get_students(self):
//!             "courses/{id}/search_users" =>
//!                 (id: self.id) -> () -> [User]
//!                 [EnrollmentType::Student]
//!     }
//! }
//! ```
//!
//! First, you write the (optional) documentation string, for use in this generated
//! documentation, followed by the function/method name.
//! If it is a method, the `self` keyword is used between the parentheses.
//! Next, you write the request url, without the base url and without `/api/v1/`.
//! The full request is generated using the `CanvasInformation` struct.
//! The request url can contain named parameters.
//! The `self` arguments are defined in the first group and the function arguments are
//! passed in the second group.
//! Finaly, the return type of the request is defined by passing the returned struct.
//! Square brackets are used when a `Vec` is returned by the API.
//! Optionaly, requests parameters can be added.

#![allow(dead_code, unused)]

#[macro_use]
pub mod parameters;
#[macro_use]
mod requests;

pub mod canvas;
pub mod models;

pub mod prelude {
    pub use super::canvas::CanvasInformation;
    pub use super::models::prelude::*;
    pub use super::parameters::*;
}