Canvas LMS API

Source: R/package.R

Minimal wrapper to access the Canvas LMS API.

This is an extremely minimal client. You need to know the API to be able to use this client. All this function does is:

  • Try to substitute each listed parameter into endpoint, using the :parameter notation.

  • If a GET request (the default), then add all other listed parameters as query parameters.

  • If not a GET request, then send the other parameters in the request body, as JSON.

  • Convert the response to an R list using jsonlite::fromJSON.

cnvs(
  endpoint = "/api/v1/courses",
  ...,
  per_page = NULL,
  .token = NULL,
  .destfile = NULL,
  .overwrite = FALSE,
  .api_url = NULL,
  .method = "GET",
  .limit = NULL,
  .send_headers = NULL
)

Arguments

endpoint

Canvas LMS API endpoint. Must be one of the following forms:

  • "METHOD path", e.g. "GET /api/v1/courses"

  • "path", e.g. "/api/v1/courses".

  • "METHOD url", e.g. "GET https://canvas.instructure.com/api/v1/courses"

  • "url", e.g. "https://canvas.instructure.com/api/v1/courses".

If the method is not supplied, will use .method, which defaults to GET.
...

Name-value pairs giving API parameters. Will be matched into url placeholders, sent as query parameters in GET requests, and in the JSON body of POST requests.
per_page

Number of items to return per page. If omitted, will be substituted by max(.limit, 100) if .limit is set, otherwise determined by the API (never greater than 100).
.token

Authentication token. Defaults to CANVAS_API_TOKEN environment variable, if set.
.destfile

path to write response to disk. If NULL (default), response will be processed and returned as an object. If path is given, response will be written to disk in the form sent.
.overwrite

if destfile is provided, whether to overwrite an existing file. Defaults to FALSE.
.api_url

Canvas domain. Used if endpoint just contains a path. Defaults to CANVAS_DOMAIN environment variable, if set.
.method

HTTP method to use if not explicitly supplied in the endpoint.
.limit

Number of records to return. This can be used instead of manual pagination. By default it is NULL, which means that the defaults of the Canvas API are used. You can set it to a number to request more (or less) records, and also to Inf to request all records. Note, that if you request many records, then multiple Canva API calls are used to get them, and this can take a potentially long time.
.send_headers

Named character vector of header field values (excepting Authorization, which is handled via .token). This can be used to override or augment the defaults, which are as follows: the Accept field defaults to "application/json", the User-Agent field defaults to "https://github.com/cwickham/cnvs", and the Content-Type defaults to "application/json".

Value

Answer from the API as a cnvs_response object, which is also a list. Failed requests will generate an R error. Requests that generate a raw response will return a raw vector.

See also

cnvs_whoami() for details on Canvas API token management.

Examples

if (FALSE) {
## Your courses
cnvs("/api/v1/courses")
}