https://github.com/cwickham/cnvs
Experimental R package to access Canvas LMS API based on gh
https://github.com/cwickham/cnvs
Last synced: 5 months ago
JSON representation
Experimental R package to access Canvas LMS API based on gh
- Host: GitHub
- URL: https://github.com/cwickham/cnvs
- Owner: cwickham
- License: other
- Created: 2019-09-30T16:42:34.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-10-16T20:14:13.000Z (over 5 years ago)
- Last Synced: 2025-04-07T12:50:10.201Z (about 1 year ago)
- Language: R
- Homepage: https://cwickham.github.io/cnvs/
- Size: 607 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# cnvs
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://travis-ci.org/cwickham/cnvs)
Minimalistic client to access the
[Canvas LMS API](https://canvas.instructure.com/doc/api/index.html). Heavily borrowing from the infrastructure of [gh](https://github.com/r-lib/gh)
## Philospophy
cnvs is intentionally minimalist. To use it, you will need to become familiar with the [Canvas API documentation](https://canvas.instructure.com/doc/api/index.html). cnvs does no checking on the endpoints you provide, nor the objects you pass. This has the advantage that cnvs is not dependent on the specifics of the Canvas API. cnvs also does no parsing of response content, you will need to extract the desired information from the returned lists yourself.
While cnvs does facilite the automation of repetitive tasks in Canvas from R, it still requires a fair bit of expertise from the user. The hope is to use it as a foundation for a higher level api package, that is more user-friendly.
## Installation
Install the package from GitHub:
```{r eval = FALSE}
# install.packages("remotes")
remotes::install_github("cwickham/cnvs")
```
## Usage
```{r}
library(cnvs)
```
Use the `cnvs()` function to access all API endpoints. The endpoints are
listed in the [documentation](https://canvas.instructure.com/doc/api/index.html).
The first argument of `cnvs()` is the endpoint. Note that the leading `/api/v1/` must be included as well, but this facilitates copy and pasting directly from the documentation. Parameters can be passed as extra arguments. E.g.
```{r}
my_courses <- cnvs("/api/v1/courses", enrollment_type = "teacher")
vapply(my_courses, "[[", "", "name")
```
The JSON result sent by the API is converted to an R object.
If the end point itself has parameters, these can also be passed
as extra arguments:
```{r}
test_modules <- cnvs("/api/v1/courses/:course_id/modules",
course_id = 1732420)
vapply(test_modules, "[[", "", "name")
```
### POST, PATCH, PUT and DELETE requests
POST, PUT, and DELETE requests can be sent by including the
HTTP verb before the endpoint, in the first argument. For example, to
create a module:
```{r}
new_module <- cnvs("POST /api/v1/courses/:course_id/modules",
course_id = 1732420, # set a parameter in the endpoint `:course_id`
module = list( # a parameter sent in the body
name = "First module",
position = 1
)
)
```
```{r}
test_modules <- cnvs("/api/v1/courses/:course_id/modules",
course_id = 1732420)
vapply(test_modules, "[[", "", "name")
```
Then update the name of the module:
```{r}
update_module <- cnvs("PUT /api/v1/courses/:course_id/modules/:id",
course_id = 1732420,
id = new_module$id,
module = list(
name = "Module 1"
)
)
```
```{r}
test_modules <- cnvs("/api/v1/courses/:course_id/modules",
course_id = 1732420)
vapply(test_modules, "[[", "", "name")
```
Then, finally, delete the module:
```{r}
cnvs("DELETE /api/v1/courses/:course_id/modules/:id",
course_id = 1732420,
id = new_module$id
)
```
```{r}
test_modules <- cnvs("/api/v1/courses/:course_id/modules",
course_id = 1732420)
vapply(test_modules, "[[", "", "name")
```
### Uploading files
To upload files use the `cnvs_upload()` function. You need to locate the endpoint for the required context of the file. E.g. To [upload a course file](https://canvas.instructure.com/doc/api/courses.html#method.courses.create_file) the endpoint is:
```
POST /api/v1/courses/:course_id/files
```
Whereas to [upload a file as an submission](https://canvas.instructure.com/doc/api/submissions.html#method.submissions_api.create_file) the endpoint is:
```
POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/files
```
Pass this endpoint to `cnvs_upload()` along with path to the file you wish to upload:
```{r, eval = FALSE}
cnvs_upload("/api/v1/courses/:course_id/files",
path = "notes.pdf", course_id = "1732420", parent_folder_path = "handouts/")
```
Like `cnvs()` you can specify parameters in the endpoint, like `course_id`, or parameters in the body of the request like `parent_folder_path` as additional arguments.
### Pagination
Supply the `page` parameter to get subsequent pages:
```{r eval = FALSE}
my_courses2 <- cnvs("/api/v1/courses", enrollment_type = "teacher",
page = 2)
vapply(my_courses2, "[[", "", "name")
```
## License
cnvs: MIT © Charlotte Wickham
The code is mostly minor edits to the [gh](https://github.com/r-lib/gh) package:
gh: MIT © Gábor Csárdi, Jennifer Bryan, Hadley Wickham