:panda_face: canvas-api

A collection of helper methods for the Canvas LMS API.

Installation

Using npm:

npm install canvas-api --save

Using Yarn:

yarn add canvas-api

Configuration and Authorization

canvas-api requires some credentials for authenticating with your organization's Canvas instance - an API key and the domain of your Canvas instance, as well as some operational settings. You can provide these credentials by setting the following environment variables accordingly:

Environment Variable | Example | Description ---------------------------------|--------------------------------|--- CANVAS_API_VERSION | v1 | API version CANVAS_API_DIFFING_DROP_STATUS | 'completed' | Parameter for Import SIS Data endpoint CANVAS_API_DOMAIN | organisation.instructure.com | Your organisation's Canvas domain CANVAS_API_KEY | secret | Your API key CANVAS_API_THROTTLE | 1000 | Delay in ms between requests for helpers.getAllResources()

Usage

require the module in your node.js application and invoke methods accordingly.

const canvas = require('canvas-api');

Methods

Common Helpers

helpers.getAllResources(options, callback)

Iterates over the pagination URLs returned by the Canvas API, captures the results from each iteration, and then returns an array of results once complete.

Values for options are:

options.url

(Required) API endpoint URL

options.data

(Optional) Query string variables

Example:

let options = {
  url: `https://organisation.instructure.com/api/v1/accounts/1/courses`,
  data: {
    per_page: 100
  }
};

canvas.helpers.getAllResources(options, (error, results) => {
  if (error) {
    console.error(error);
    // Error!
  } else {
    console.log(results);
    // [ results ... ]
  }
});

Courses

course.migrate(source, destination, callback)

Migrates the content of one course to another using the course_copy_importer migration type.

source

(Required) course_id of the course that will be copied from.

destination

(Required) course_id of the course that will be copied to.

Example:

canvas.course.migrate(1, 110, (error, results) => {
  if (error) {
    console.error(error);
    // Error!
  } else {
    console.log(results.body);
    // {
    //   id: 401,
    //   ...
    // }
  }
});

course.discuss(course, params, callback)

Create a discussion topic in the desired course.

course is the ID of the Canvas course that you wish to create the discussion topic in.

params must be an object containing any of the parameters listed here. nment[name]`.

Example:

var createParams = {
  title: ' This is the subject message title',
  message: 'This is a message'
  }
};

course.discuss(123, createParams, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

SIS Imports

sis.upload(options, callback)

POSTs a CSV file to the SIS Import endpoint that is formatted to match Instructure's SIS CSV Format. Upon success, a SIS Import Object is returned.

options should be an object containing the following information:

Key | Required | Description | Example ----------|----------|--------------------------------|-------- csv | yes | Path to CSV | './path/to/file.csv' dataset | yes | Dataset that is being imported | 'courses'

Example:

canvas.sis.upload({
  csv: './csv/courses.csv',
  dataset: 'courses'
}, (error, results) => {
  if (error) {
    console.error(error);
    // Error!
  } else {
    console.log(results);
    // [ results ... ]
  }
});

sis.status(scope, callback)

Return SIS Import status information.

scope can either be:

• 'all' - returns the latest 10 SIS Import objects.
• Number - returns the SIS Import with the ID corresponding to the supplied Number.

If scope is not supplied, the latest 10 SIS Import objects are returned.

Example:

canvas.sis.status(10, (error, results) => {
  if (error) {
    console.error(error);
    // Error!
  } else {
    console.log(results);
    // [ results ... ]
  }
});

Assignments

assignment.get(course, id, callback)

Get an existing assignment by id in the desired course.

course is the ID of the Canvas course that you wish to get the assignment from.

id is the ID of the Assignment that you wish to get.

Example:

assignment.create(123, 1001, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

assignment.create(course, params, callback)

Create an assignment in the desired course.

course is the ID of the Canvas course that you wish to create the assignment in.

params must be an object containing any of the parameters listed here. The only required parameter is assignment[name]. The object must be structured as shown in the example below:

Example:

var createParams = {
  assignment: {
    name: 'Assignment Name',
    points_possible: 100
  }
};

assignment.create(123, createParams, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

assignment.edit(course, id, params, callback)

Edit an existing assignment by ID in the desired course.

course is the ID of the Canvas course that contains the assignment that you wish to edit.

id is the ID of the assignment that you wish to edit.

params must be an object containing any of the parameters listed here. The object must be structured as shown in the example below:

Example:

var editParams = {
  assignment: {
    name: 'Assignment Name (Edited)',
    points_possible: 50
  }
};

assignment.edit(123, 4567, editParams, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

assignment.searchbyname(course, name, callback)

Search for an existing assignment by name in the desired course.

course is the ID of the Canvas course that contains the assignment that you wish to edit.

name is the substring of the name of the assignment that you wish to find.

Example:

assignment.searchbyname(123, name, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

assignment.delete(course, id, callback)

Delete an assignment in the desired course.

course is the ID of the Canvas course that contains the assignment that you wish to delete.

id is the ID of the assignment that you wish to delete.

Example:

assignment.delete(123, 4567, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

Modules

cmodule.get(course, id, callback)

Get an existing cmodule by id in the desired course.

course is the ID of the Canvas course that you wish to get the cmodule from.

id is the ID of the cmodule that you wish to get.

Example:

cmodule.create(123, 1001, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

cmodule.create(course, params, callback)

Create an cmodule in the desired course.

course is the ID of the Canvas course that you wish to create the cmodule in.

params must be an object containing any of the parameters listed here.

Example:

var createParams = {
  module: {
    name: 'cmodule Name'
  }
};

cmodule.create(123, createParams, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

cmodule.edit(course, id, params, callback)

Edit an existing cmodule by ID in the desired course.

course is the ID of the Canvas course that contains the cmodule that you wish to edit.

id is the ID of the cmodule that you wish to edit.

params must be an object containing any of the parameters listed here. The object must be structured as shown in the example below:

Example:

var editParams = {
  module: {
    name: 'cmodule Name (Edited)'

  }
};

cmodule.edit(123, 4567, editParams, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

cmodule.searchbyname(course, name, callback)

Search for an existing cmodule by name in the desired course.

course is the ID of the Canvas course that contains the cmodule that you wish to edit.

name is the substring of the name of the cmodule that you wish to find.

Example:

cmodule.searchbyname(123, name, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

cmodule.delete(course, id, callback)

Delete an cmodule in the desired course.

course is the ID of the Canvas course that contains the cmodule that you wish to delete.

id is the ID of the cmodule that you wish to delete.

Example:

cmodule.delete(123, 4567, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

Rubrics

rubric.list(course, params, (callback)

List rubrics used in the desired course.

Example:

var params = {
  data: {
    per_page: 100
  }
};

rubric.list(123, params, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

rubric.detail(course, assignment, params, (callback)

List rubric details for a desired assignment in a course.

Example:

var params = {
  data: {
    per_page: 100
  }
};

rubric.detail(123, 4567, params, (error, results) => {
  if (error) {
    // Error!
  } else {
    // [ results ... ]
  }
});

Tests

The canvas-api test suite requires some environment variables to be set:

Environment Variable | Description | Example -------------------------------------|-------------|-------- CANVAS_API_TEST_MIGRATION_SRC_ID | course_id of the 'source' course to test Course Migration | 1 CANVAS_API_TEST_MIGRATION_DEST_ID | course_id of the 'destination' course to test Course Migration | 110 CANVAS_API_TEST_COURSE_ID | course_id of the course to use for creating, editing, deleting assignments | 123 CANVAS_API_TEST_RUBRIC_COURSE_ID | course_id of the course to use for getting Rubric detail | 123 CANVAS_API_TEST_RUBRIC_ASSIGNMENT_ID | assignment_id of the assignment to use for getting Rubric detail | 4567

The suite can be run by executing the test script contained in package.json:

Using npm:

npm run test

Using Yarn:

yarn run test