canvas-api v3.6.0

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

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

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:

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:

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

Using npm:

npm run test

Using Yarn:

yarn run test