README.md

In cwickham/cnvs: 'Canvas LMS' 'API'

cnvs

Minimalistic client to access the Canvas LMS API. Heavily borrowing from the infrastructure of gh

Philospophy

cnvs is intentionally minimalist. To use it, you will need to become familiar with the Canvas API documentation. 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:

# install.packages("remotes")
remotes::install_github("cwickham/cnvs")

Usage

library(cnvs)

Use the cnvs() function to access all API endpoints. The endpoints are listed in the documentation.

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.

my_courses <- cnvs("/api/v1/courses", enrollment_type = "teacher")
vapply(my_courses, "[[", "", "name")
#> [1] "ST499/599 Topics in Data Visualization"
#> [2] "ST505 for ST511"                       
#> [3] "ST511 Summer 2017"                     
#> [4] "Stat 499/599, Data Programming in R"   
#> [5] "Testing for cnvs"

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:

test_modules <- cnvs("/api/v1/courses/:course_id/modules", 
  course_id = 1732420)
vapply(test_modules, "[[", "", "name")
#> [1] "First module" "First module" "First module" "First module"
#> [5] "First module" "Test module"  "First module"

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:

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
  )
)

test_modules <- cnvs("/api/v1/courses/:course_id/modules", 
  course_id = 1732420)
vapply(test_modules, "[[", "", "name")
#> [1] "First module" "First module" "First module" "First module"
#> [5] "First module" "First module" "Test module"  "First module"

Then update the name of the module:

update_module <- cnvs("PUT /api/v1/courses/:course_id/modules/:id",
  course_id = 1732420,
  id = new_module$id,
  module = list(
    name = "Module 1"
  )
)

test_modules <- cnvs("/api/v1/courses/:course_id/modules", 
  course_id = 1732420)
vapply(test_modules, "[[", "", "name")
#> [1] "Module 1"     "First module" "First module" "First module"
#> [5] "First module" "First module" "Test module"  "First module"

Then, finally, delete the module:

cnvs("DELETE /api/v1/courses/:course_id/modules/:id",
  course_id = 1732420,
  id = new_module$id
)
#> {
#>   "id": 3539337,
#>   "position": 1,
#>   "name": "Module 1",
#>   "unlock_at": {},
#>   "require_sequential_progress": false,
#>   "publish_final_grade": false,
#>   "prerequisite_module_ids": [],
#>   "published": false,
#>   "items_count": 0,
#>   "items_url": "https://canvas.instructure.com/api/v1/courses/1732420/modules/3539337/items"
#> }

test_modules <- cnvs("/api/v1/courses/:course_id/modules", 
  course_id = 1732420)
vapply(test_modules, "[[", "", "name")
#> [1] "First module" "First module" "First module" "First module"
#> [5] "First module" "Test module"  "First module"

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 the endpoint is:

POST /api/v1/courses/:course_id/files

Whereas to upload a file as an submission 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:

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:

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 package:

gh: MIT © Gábor Csárdi, Jennifer Bryan, Hadley Wickham

cwickham/cnvs documentation built on Oct. 20, 2020, 5:34 a.m.