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

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

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

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

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

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

Then, finally, delete the module:

cnvs("DELETE /api/v1/courses/:course_id/modules/:id",
  course_id = 1732420,
  id = new_module$id
)

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